From cd165e8e0f739db2326773ca3fe39056d3832d47 Mon Sep 17 00:00:00 2001 From: Simon McVittie Date: Mon, 21 Oct 2013 19:27:18 +0100 Subject: [PATCH 14/16] Add more pseudo-doc-comments to teach g-i about TpBaseProtocol --- telepathy-glib/base-protocol.c | 159 ++++++++++++++++++++++++++++++++++++++++- 1 file changed, 157 insertions(+), 2 deletions(-) diff --git a/telepathy-glib/base-protocol.c b/telepathy-glib/base-protocol.c index aa70d50..bc460a1 100644 --- a/telepathy-glib/base-protocol.c +++ b/telepathy-glib/base-protocol.c @@ -294,6 +294,23 @@ tp_cm_param_filter_string_nonempty (const TpCMParamSpec *paramspec, */ /** + * TpBaseProtocolClass::get_parameters: + * @self: a protocol + * + * Virtual method to get the allowed parameters for connections + * to a protocol. + * + * Returns the parameters supported by this protocol, as an array of structs + * which must remain valid at least as long as @self exists (it will typically + * be a global static array). + * + * Returns: (transfer none) (array zero-terminated=1): a description of the + * parameters supported by this protocol + * + * Since: 0.11.11 + */ + +/** * TpBaseProtocolNewConnectionFunc: * @self: a protocol * @asv: (transfer none) (element-type utf8 GObject.Value): the parameters @@ -313,6 +330,24 @@ tp_cm_param_filter_string_nonempty (const TpCMParamSpec *paramspec, */ /** + * TpBaseProtocolClass::new_connection: + * @self: a protocol + * @asv: (transfer none) (element-type utf8 GObject.Value): the parameters + * provided via D-Bus + * @error: used to return an error if %NULL is returned + * + * Create a new connection to this protocol. + * This is used to implement the RequestConnection D-Bus method. + * + * Implementations of #TpBaseProtocolClass.new_connection may assume that + * the parameters in @asv conform to the specifications given by + * #TpBaseProtocolClass.get_parameters. + * + * Returns: (transfer full): a new connection, or %NULL on error + * Since: 0.11.11 + */ + +/** * TpBaseProtocolNormalizeContactFunc: * @self: a protocol * @contact: a contact's identifier @@ -328,6 +363,21 @@ tp_cm_param_filter_string_nonempty (const TpCMParamSpec *paramspec, */ /** + * TpBaseProtocol::normalize_contact: + * @self: a protocol + * @contact: a contact's identifier + * @error: used to return an error if %NULL is returned + * + * Perform best-effort offline normalization + * of a contact's identifier: either return a newly allocated string + * that is the normalized form of @contact, or raise an error and return %NULL. + * + * Returns: (transfer full): a normalized identifier, or %NULL on error + * + * Since: 0.11.11 + */ + +/** * TpBaseProtocolIdentifyAccountFunc: * @self: a protocol * @asv: parameters that might be passed to the RequestConnection D-Bus method @@ -348,6 +398,26 @@ tp_cm_param_filter_string_nonempty (const TpCMParamSpec *paramspec, */ /** + * TpBaseProtocol::identify_account: + * @self: a protocol + * @asv: parameters that might be passed to the RequestConnection D-Bus method + * @error: used to return an error if %NULL is returned + * + * Choose a unique name for an account whose + * connection parameters are @asv. This will typically return a copy of + * the 'account' parameter from @asv, but may do something more complex (for + * instance, on IRC it could combine the nickname and the IRC network). + * + * Implementations of #TpBaseProtocolClass.identify_account may assume that + * the parameters in @asv conform to the specifications given by + * #TpBaseProtocolClass.get_parameters. + * + * Returns: (transfer full): a unique name for the account, or %NULL on error + * + * Since: 0.11.11 + */ + +/** * TpBaseProtocolGetInterfacesFunc: * @self: a protocol * @@ -388,6 +458,41 @@ tp_cm_param_filter_string_nonempty (const TpCMParamSpec *paramspec, */ /** + * TpBaseProtocol::get_connection_details: + * @self: a protocol + * @connection_interfaces: (out) (transfer full): used to return a + * %NULL-terminated array of interfaces which might be implemented on + * connections to this protocol + * @channel_manager_types: (out) (transfer full) (array zero-terminated=1): + * used to return a %G_TYPE_INVALID-terminated array of types that implement + * #TpChannelManager, which must include all channel managers that might be + * present on connections to this protocol; the channel managers should + * all implement #TpChannelManagerIface.type_foreach_channel_class. The + * array will be freed with g_free() by the caller. + * @icon_name: (out) (transfer full): used to return the name of an icon + * for this protocol, such as "im-icq", or an empty string + * @english_name: (out) (transfer full): used to return a human-readable + * but non-localized name for this protocol, or an empty string + * @vcard_field: (out) (transfer full): used to return the name of the vCard + * field typically used with this protocol, or an empty string + * + * Virtual method to get the D-Bus interfaces implemented by + * @self, in addition to the Protocol interface. + * + * Since: 0.11.11 + */ + +/** + * TpBaseProtocol::get_statuses: + * @self: a protocol + * + * Return the presence statuses supported by this protocol. + * + * Returns: (transfer none) (array zero-terminated=1): the statuses + * Since: 0.13.7 + */ + +/** * TpBaseProtocolGetAvatarDetailsFunc: * @self: a protocol * @supported_mime_types: (out) (transfer full): used to return a @@ -414,6 +519,44 @@ tp_cm_param_filter_string_nonempty (const TpCMParamSpec *paramspec, */ /** + * TpBaseProtocol::get_avatar_details: + * @self: a protocol + * @supported_mime_types: (out) (transfer full): used to return a + * %NULL-terminated array of supported avatar mime types + * @min_height: (out): used to return the minimum height in pixels of an + * avatar on this protocol, which may be 0 + * @min_width: (out): used to return the minimum width in pixels of an avatar + * on this protocol, which may be 0 + * @rec_height: (out): used to return the rec height in pixels + * of an avatar on this protocol, or 0 if there is no preferred height + * @rec_width: (out): used to return the rec width in pixels + * of an avatar on this protocol, or 0 if there is no preferred width + * @max_height: (out): used to return the maximum height in pixels of an + * avatar on this protocol, or 0 if there is no limit + * @max_width: (out): used to return the maximum width in pixels of an avatar + * on this protocol, or 0 if there is no limit + * @max_bytes: (out): used to return the maximum size in bytes of an avatar on + * this protocol, or 0 if there is no limit + * + * Get the supported avatar details for the protocol implemented by @self. + * + * Since: 0.13.7 + */ + +/** + * TpBaseProtocol::dup_authentication_types: + * @self: a protocol + * + * Return an array of channel types and/or interfaces indicating the + * channels that can appear before a connection to this protocol will + * finish connecting. + * + * Returns: (transfer full) (array zero-terminated=1) (element-type utf8): the + * authentication channel types as D-Bus interface names + * Since: 0.13.7 + */ + +/** * TpBaseProtocolGetInterfacesArrayFunc: * @self: a #TpBaseProtocol * @@ -438,8 +581,20 @@ tp_cm_param_filter_string_nonempty (const TpCMParamSpec *paramspec, * } * ]| * - * Returns: (transfer container): a #GPtrArray of static strings for D-Bus - * interfaces implemented by this client. + * Returns: (transfer container) (element-type utf8): a #GPtrArray of + * static strings for D-Bus interfaces implemented by this client. + * + * Since: 0.19.4 + */ + +/** + * TpBaseProtocol::get_interfaces_array: + * @self: a #TpBaseProtocol + * + * Return the extra interfaces implemented by this protocol. + * + * Returns: (transfer container) (element-type utf8): a #GPtrArray of + * static strings for D-Bus interfaces implemented by this protocol. * * Since: 0.19.4 */ -- 1.8.4.rc3