Disable installing plugins that aren't built.
[pidgin-git.git] / libpurple / protocol.h
blob71ada0a74261b252728657b21672d405f8fdbc04
1 /* purple
3 * Purple is the legal property of its developers, whose names are too numerous
4 * to list here. Please refer to the COPYRIGHT file distributed with this
5 * source distribution.
7 * This program is free software; you can redistribute it and/or modify
8 * it under the terms of the GNU General Public License as published by
9 * the Free Software Foundation; either version 2 of the License, or
10 * (at your option) any later version.
12 * This program is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 * GNU General Public License for more details.
17 * You should have received a copy of the GNU General Public License
18 * along with this program; if not, write to the Free Software
19 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02111-1301 USA
22 #ifndef PURPLE_PROTOCOL_H
23 #define PURPLE_PROTOCOL_H
24 /**
25 * SECTION:protocol
26 * @section_id: libpurple-protocol
27 * @short_description: <filename>protocol.h</filename>
28 * @title: Protocol Object and Interfaces
31 #define PURPLE_TYPE_PROTOCOL (purple_protocol_get_type())
32 #define PURPLE_PROTOCOL(obj) (G_TYPE_CHECK_INSTANCE_CAST((obj), PURPLE_TYPE_PROTOCOL, PurpleProtocol))
33 #define PURPLE_PROTOCOL_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST((klass), PURPLE_TYPE_PROTOCOL, PurpleProtocolClass))
34 #define PURPLE_IS_PROTOCOL(obj) (G_TYPE_CHECK_INSTANCE_TYPE((obj), PURPLE_TYPE_PROTOCOL))
35 #define PURPLE_IS_PROTOCOL_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE((klass), PURPLE_TYPE_PROTOCOL))
36 #define PURPLE_PROTOCOL_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS((obj), PURPLE_TYPE_PROTOCOL, PurpleProtocolClass))
38 typedef struct _PurpleProtocol PurpleProtocol;
39 typedef struct _PurpleProtocolClass PurpleProtocolClass;
41 #include "account.h"
42 #include "accountopt.h"
43 #include "buddyicon.h"
44 #include "buddylist.h"
45 #include "connection.h"
46 #include "conversations.h"
47 #include "debug.h"
48 #include "xfer.h"
49 #include "image.h"
50 #include "media.h"
51 #include "message.h"
52 #include "notify.h"
53 #include "plugins.h"
54 #include "roomlist.h"
55 #include "status.h"
56 #include "whiteboard.h"
58 /**
59 * PurpleProtocolOverrideFlags:
61 * Flags to indicate what base protocol's data a derived protocol wants to
62 * override.
64 * See purple_protocol_override().
66 typedef enum /*< flags >*/
68 PURPLE_PROTOCOL_OVERRIDE_USER_SPLITS = 1 << 1,
69 PURPLE_PROTOCOL_OVERRIDE_PROTOCOL_OPTIONS = 1 << 2,
70 PURPLE_PROTOCOL_OVERRIDE_ICON_SPEC = 1 << 3,
71 } PurpleProtocolOverrideFlags;
73 /**
74 * PurpleProtocol:
75 * @id: Protocol ID
76 * @name: Translated name of the protocol
77 * @options: Protocol options
78 * @user_splits: A GList of PurpleAccountUserSplit
79 * @account_options: A GList of PurpleAccountOption
80 * @icon_spec: The icon spec.
81 * @whiteboard_ops: Whiteboard operations
83 * Represents an instance of a protocol registered with the protocols
84 * subsystem. Protocols must initialize the members to appropriate values.
86 struct _PurpleProtocol
88 GObject gparent;
90 /*< public >*/
91 const char *id;
92 const char *name;
94 PurpleProtocolOptions options;
96 GList *user_splits;
97 GList *account_options;
99 PurpleBuddyIconSpec *icon_spec;
100 PurpleWhiteboardOps *whiteboard_ops;
102 /*< private >*/
103 void (*_purple_reserved1)(void);
104 void (*_purple_reserved2)(void);
105 void (*_purple_reserved3)(void);
106 void (*_purple_reserved4)(void);
110 * PurpleProtocolClass:
111 * @login: Log in to the server.
112 * @close: Close connection with the server.
113 * @status_types: Returns a list of #PurpleStatusType which exist for this
114 * account; and must add at least the offline and online states.
115 * @list_icon: Returns the base icon name for the given buddy and account. If
116 * buddy is %NULL and the account is non-%NULL, it will return
117 * the name to use for the account's icon. If both are %NULL, it
118 * will return the name to use for the protocol's icon.
120 * The base class for all protocols.
122 * All protocol types must implement the methods in this class.
124 /* If adding new methods to this class, ensure you add checks for them in
125 purple_protocols_add().
127 struct _PurpleProtocolClass
129 GObjectClass parent_class;
131 void (*login)(PurpleAccount *account);
133 void (*close)(PurpleConnection *connection);
135 GList *(*status_types)(PurpleAccount *account);
137 const char *(*list_icon)(PurpleAccount *account, PurpleBuddy *buddy);
139 /*< private >*/
140 void (*_purple_reserved1)(void);
141 void (*_purple_reserved2)(void);
142 void (*_purple_reserved3)(void);
143 void (*_purple_reserved4)(void);
146 #define PURPLE_TYPE_PROTOCOL_CLIENT_IFACE (purple_protocol_client_iface_get_type())
148 typedef struct _PurpleProtocolClientIface PurpleProtocolClientIface;
151 * PurpleProtocolClientIface:
152 * @get_actions: Returns the actions the protocol can perform. These will
153 * show up in the Accounts menu, under a submenu with the name
154 * of the account.
155 * @list_emblem: Fills the four <type>char**</type>'s with string
156 * identifiers for "emblems" that the UI will interpret and
157 * display as relevant
158 * @status_text: Gets a short string representing this buddy's status. This
159 * will be shown on the buddy list.
160 * @tooltip_text: Allows the protocol to add text to a buddy's tooltip.
161 * @blist_node_menu: Returns a list of #PurpleActionMenu structs, which
162 * represent extra actions to be shown in (for example) the
163 * right-click menu for @node.
164 * @normalize: Convert the username @who to its canonical form. Also checks for
165 * validity.
166 * <sbr/>For example, AIM treats "fOo BaR" and "foobar" as the same
167 * user; this function should return the same normalized string for
168 * both of those. On the other hand, both of these are invalid for
169 * protocols with number-based usernames, so function should return
170 * %NULL in such case.
171 * <sbr/>@account: The account the username is related to. Can be
172 * %NULL.
173 * <sbr/>@who: The username to convert.
174 * <sbr/>Returns: Normalized username, or %NULL, if it's invalid.
175 * @offline_message: Checks whether offline messages to @buddy are supported.
176 * <sbr/>Returns: %TRUE if @buddy can be sent messages while
177 * they are offline, or %FALSE if not.
178 * @get_account_text_table: This allows protocols to specify additional strings
179 * to be used for various purposes. The idea is to
180 * stuff a bunch of strings in this hash table instead
181 * of expanding the struct for every addition. This
182 * hash table is allocated every call and
183 * <emphasis>MUST</emphasis> be unrefed by the caller.
184 * <sbr/>@account: The account to specify. This can be
185 * %NULL.
186 * <sbr/>Returns: The protocol's string hash table.
187 * The hash table should be destroyed
188 * by the caller when it's no longer
189 * needed.
190 * @get_moods: Returns an array of #PurpleMood's, with the last one having
191 * "mood" set to %NULL.
192 * @get_max_message_size: Gets the maximum message size in bytes for the
193 * conversation.
194 * <sbr/>It may depend on connection-specific or
195 * conversation-specific variables, like channel or
196 * buddy's name length.
197 * <sbr/>This value is intended for plaintext message,
198 * the exact value may be lower because of:
199 * <sbr/> - used newlines (some protocols count them as
200 * more than one byte),
201 * <sbr/> - formatting,
202 * <sbr/> - used special characters.
203 * <sbr/>@conv: The conversation to query, or NULL to
204 * get safe minimum for the protocol.
205 * <sbr/>Returns: Maximum message size, 0 if unspecified,
206 * -1 for infinite.
208 * The protocol client interface.
210 * This interface provides a gateway between purple and the protocol.
212 struct _PurpleProtocolClientIface
214 /*< private >*/
215 GTypeInterface parent_iface;
217 /*< public >*/
218 GList *(*get_actions)(PurpleConnection *connection);
220 const char *(*list_emblem)(PurpleBuddy *buddy);
222 char *(*status_text)(PurpleBuddy *buddy);
224 void (*tooltip_text)(PurpleBuddy *buddy, PurpleNotifyUserInfo *user_info,
225 gboolean full);
227 GList *(*blist_node_menu)(PurpleBlistNode *node);
229 void (*buddy_free)(PurpleBuddy *buddy);
231 void (*convo_closed)(PurpleConnection *connection, const char *who);
233 const char *(*normalize)(const PurpleAccount *account, const char *who);
235 PurpleChat *(*find_blist_chat)(PurpleAccount *account, const char *name);
237 gboolean (*offline_message)(const PurpleBuddy *buddy);
239 GHashTable *(*get_account_text_table)(PurpleAccount *account);
241 PurpleMood *(*get_moods)(PurpleAccount *account);
243 gssize (*get_max_message_size)(PurpleConversation *conv);
246 #define PURPLE_PROTOCOL_HAS_CLIENT_IFACE(obj) (G_TYPE_CHECK_INSTANCE_TYPE((obj), PURPLE_TYPE_PROTOCOL_CLIENT_IFACE))
247 #define PURPLE_PROTOCOL_GET_CLIENT_IFACE(obj) (G_TYPE_INSTANCE_GET_INTERFACE((obj), PURPLE_TYPE_PROTOCOL_CLIENT_IFACE, \
248 PurpleProtocolClientIface))
250 #define PURPLE_TYPE_PROTOCOL_SERVER_IFACE (purple_protocol_server_iface_get_type())
252 typedef struct _PurpleProtocolServerIface PurpleProtocolServerIface;
255 * PurpleProtocolServerIface:
256 * @register_user: New user registration
257 * @unregister_user: Remove the user from the server. The account can either be
258 * connected or disconnected. After the removal is finished,
259 * the connection will stay open and has to be closed!
260 * @get_info: Should arrange for purple_notify_userinfo() to be called
261 * with @who's user info.
262 * @add_buddy: Add a buddy to a group on the server.
263 * <sbr/>This protocol function may be called in situations in
264 * which the buddy is already in the specified group. If the
265 * protocol supports authorization and the user is not already
266 * authorized to see the status of @buddy, @add_buddy should
267 * request authorization.
268 * <sbr/>If authorization is required, then use the supplied
269 * invite message.
270 * @keepalive: If implemented, this will be called regularly for this
271 * protocol's active connections. You'd want to do this if you
272 * need to repeatedly send some kind of keepalive packet to
273 * the server to avoid being disconnected. ("Regularly" is
274 * defined to be 30 unless get_keepalive_interval() is
275 * implemented to override it).
276 * <filename>libpurple/connection.c</filename>.)
277 * @get_keepalive_interval: If implemented, this will override the default
278 * keepalive interval.
279 * @alias_buddy: Save/store buddy's alias on server list/roster
280 * @group_buddy: Change a buddy's group on a server list/roster
281 * @rename_group: Rename a group on a server list/roster
282 * @set_buddy_icon: Set the buddy icon for the given connection to @img. The
283 * protocol does <emphasis>NOT</emphasis> own a reference to
284 * @img; if it needs one, it must #g_object_ref(@img)
285 * itself.
286 * @send_raw: For use in plugins that may understand the underlying
287 * protocol
288 * @set_public_alias: Set the user's "friendly name" (or alias or nickname or
289 * whatever term you want to call it) on the server. The
290 * protocol should call @success_cb or @failure_cb
291 * <emphasis>asynchronously</emphasis> (if it knows
292 * immediately that the set will fail, call one of the
293 * callbacks from an idle/0-second timeout) depending on if
294 * the nickname is set successfully. See
295 * purple_account_set_public_alias().
296 * <sbr/>@gc: The connection for which to set an alias
297 * <sbr/>@alias: The new server-side alias/nickname for this
298 * account, or %NULL to unset the
299 * alias/nickname (or return it to a
300 * protocol-specific "default").
301 * <sbr/>@success_cb: Callback to be called if the public
302 * alias is set
303 * <sbr/>@failure_cb: Callback to be called if setting the
304 * public alias fails
305 * @get_public_alias: Retrieve the user's "friendly name" as set on the server.
306 * The protocol should call @success_cb or @failure_cb
307 * <emphasis>asynchronously</emphasis> (even if it knows
308 * immediately that the get will fail, call one of the
309 * callbacks from an idle/0-second timeout) depending on if
310 * the nickname is retrieved. See
311 * purple_account_get_public_alias().
312 * <sbr/>@gc: The connection for which to retireve
313 * the alias
314 * <sbr/>@success_cb: Callback to be called with the
315 * retrieved alias
316 * <sbr/>@failure_cb: Callback to be called if the protocol
317 * is unable to retrieve the alias
319 * The protocol server interface.
321 * This interface provides a gateway between purple and the protocol's server.
323 struct _PurpleProtocolServerIface
325 /*< private >*/
326 GTypeInterface parent_iface;
328 /*< public >*/
329 void (*register_user)(PurpleAccount *account);
331 void (*unregister_user)(PurpleAccount *account, PurpleAccountUnregistrationCb cb,
332 void *user_data);
334 void (*set_info)(PurpleConnection *connection, const char *info);
336 void (*get_info)(PurpleConnection *connection, const char *who);
338 void (*set_status)(PurpleAccount *account, PurpleStatus *status);
340 void (*set_idle)(PurpleConnection *connection, int idletime);
342 void (*change_passwd)(PurpleConnection *connection, const char *old_pass,
343 const char *new_pass);
345 void (*add_buddy)(PurpleConnection *pc, PurpleBuddy *buddy,
346 PurpleGroup *group, const char *message);
348 void (*add_buddies)(PurpleConnection *pc, GList *buddies, GList *groups,
349 const char *message);
351 void (*remove_buddy)(PurpleConnection *connection, PurpleBuddy *buddy,
352 PurpleGroup *group);
354 void (*remove_buddies)(PurpleConnection *connection, GList *buddies, GList *groups);
356 void (*keepalive)(PurpleConnection *connection);
358 int (*get_keepalive_interval)(void);
360 void (*alias_buddy)(PurpleConnection *connection, const char *who,
361 const char *alias);
363 void (*group_buddy)(PurpleConnection *connection, const char *who,
364 const char *old_group, const char *new_group);
366 void (*rename_group)(PurpleConnection *connection, const char *old_name,
367 PurpleGroup *group, GList *moved_buddies);
369 void (*set_buddy_icon)(PurpleConnection *connection, PurpleImage *img);
371 void (*remove_group)(PurpleConnection *gc, PurpleGroup *group);
373 int (*send_raw)(PurpleConnection *gc, const char *buf, int len);
375 void (*set_public_alias)(PurpleConnection *gc, const char *alias,
376 PurpleSetPublicAliasSuccessCallback success_cb,
377 PurpleSetPublicAliasFailureCallback failure_cb);
379 void (*get_public_alias)(PurpleConnection *gc,
380 PurpleGetPublicAliasSuccessCallback success_cb,
381 PurpleGetPublicAliasFailureCallback failure_cb);
384 #define PURPLE_PROTOCOL_HAS_SERVER_IFACE(obj) (G_TYPE_CHECK_INSTANCE_TYPE((obj), PURPLE_TYPE_PROTOCOL_SERVER_IFACE))
385 #define PURPLE_PROTOCOL_GET_SERVER_IFACE(obj) (G_TYPE_INSTANCE_GET_INTERFACE((obj), PURPLE_TYPE_PROTOCOL_SERVER_IFACE, \
386 PurpleProtocolServerIface))
388 #define PURPLE_TYPE_PROTOCOL_IM_IFACE (purple_protocol_im_iface_get_type())
390 typedef struct _PurpleProtocolIMIface PurpleProtocolIMIface;
393 * PurpleProtocolIMIface:
394 * @send: This protocol function should return a positive value on
395 * success. If the message is too big to be sent, return
396 * <literal>-E2BIG</literal>. If the account is not connected,
397 * return <literal>-ENOTCONN</literal>. If the protocol is unable
398 * to send the message for another reason, return some other
399 * negative value. You can use one of the valid #errno values, or
400 * just big something. If the message should not be echoed to the
401 * conversation window, return 0.
402 * @send_typing: If this protocol requires the #PURPLE_IM_TYPING message to be
403 * sent repeatedly to signify that the user is still typing, then
404 * the protocol should return the number of seconds to wait before
405 * sending a subsequent notification. Otherwise the protocol
406 * should return 0.
408 * The protocol IM interface.
410 * This interface provides callbacks needed by protocols that implement IMs.
412 struct _PurpleProtocolIMIface
414 /*< private >*/
415 GTypeInterface parent_iface;
417 /*< public >*/
418 int (*send)(PurpleConnection *connection, PurpleMessage *msg);
420 unsigned int (*send_typing)(PurpleConnection *connection, const char *name,
421 PurpleIMTypingState state);
424 #define PURPLE_PROTOCOL_HAS_IM_IFACE(obj) (G_TYPE_CHECK_INSTANCE_TYPE((obj), PURPLE_TYPE_PROTOCOL_IM_IFACE))
425 #define PURPLE_PROTOCOL_GET_IM_IFACE(obj) (G_TYPE_INSTANCE_GET_INTERFACE((obj), PURPLE_TYPE_PROTOCOL_IM_IFACE, \
426 PurpleProtocolIMIface))
428 #define PURPLE_TYPE_PROTOCOL_CHAT_IFACE (purple_protocol_chat_iface_get_type())
430 typedef struct _PurpleProtocolChatIface PurpleProtocolChatIface;
433 * PurpleProtocolChatIface:
434 * @info: Returns a list of #PurpleProtocolChatEntry structs, which represent
435 * information required by the protocol to join a chat. libpurple will
436 * call join_chat along with the information filled by the user.
437 * <sbr/>Returns: A list of #PurpleProtocolChatEntry's
438 * @info_defaults: Returns a hashtable which maps #PurpleProtocolChatEntry
439 * struct identifiers to default options as strings based on
440 * @chat_name. The resulting hashtable should be created with
441 * #g_hash_table_new_full(#g_str_hash, #g_str_equal, %NULL,
442 * #g_free). Use @get_name if you instead need to extract a chat
443 * name from a hashtable.
444 * <sbr/>@chat_name: The chat name to be turned into components
445 * <sbr/>Returns: Hashtable containing the information extracted
446 * from @chat_name
447 * @join: Called when the user requests joining a chat. Should arrange for
448 * purple_serv_got_joined_chat() to be called.
449 * <sbr/>@components: A hashtable containing information required to join
450 * the chat as described by the entries returned by
451 * @info. It may also be called when accepting an
452 * invitation, in which case this matches the data
453 * parameter passed to purple_serv_got_chat_invite().
454 * @reject: Called when the user refuses a chat invitation.
455 * <sbr/>@components: A hashtable containing information required to
456 * join the chat as passed to purple_serv_got_chat_invite().
457 * @get_name: Returns a chat name based on the information in components. Use
458 * @info_defaults if you instead need to generate a hashtable from a
459 * chat name.
460 * <sbr/>@components: A hashtable containing information about the
461 * chat.
462 * @invite: Invite a user to join a chat.
463 * <sbr/>@id: The id of the chat to invite the user to.
464 * <sbr/>@message: A message displayed to the user when the invitation
465 * is received.
466 * <sbr/>@who: The name of the user to send the invation to.
467 * @leave: Called when the user requests leaving a chat.
468 * <sbr/>@id: The id of the chat to leave
469 * @send: Send a message to a chat.
470 * <sbr/>This protocol function should return a positive value on
471 * success. If the message is too big to be sent, return
472 * <literal>-E2BIG</literal>. If the account is not connected,
473 * return <literal>-ENOTCONN</literal>. If the protocol is unable
474 * to send the message for another reason, return some other
475 * negative value. You can use one of the valid #errno values, or
476 * just big something.
477 * <sbr/>@id: The id of the chat to send the message to.
478 * <sbr/>@msg: The message to send to the chat.
479 * <sbr/>Returns: A positive number or 0 in case of success, a
480 * negative error number in case of failure.
481 * @get_user_real_name: Gets the real name of a participant in a chat. For
482 * example, on XMPP this turns a chat room nick
483 * <literal>foo</literal> into
484 * <literal>room\@server/foo</literal>.
485 * <sbr/>@gc: the connection on which the room is.
486 * <sbr/>@id: the ID of the chat room.
487 * <sbr/>@who: the nickname of the chat participant.
488 * <sbr/>Returns: the real name of the participant. This
489 * string must be freed by the caller.
491 * The protocol chat interface.
493 * This interface provides callbacks needed by protocols that implement chats.
495 struct _PurpleProtocolChatIface
497 /*< private >*/
498 GTypeInterface parent_iface;
500 /*< public >*/
501 GList *(*info)(PurpleConnection *connection);
503 GHashTable *(*info_defaults)(PurpleConnection *connection, const char *chat_name);
505 void (*join)(PurpleConnection *connection, GHashTable *components);
507 void (*reject)(PurpleConnection *connection, GHashTable *components);
509 char *(*get_name)(GHashTable *components);
511 void (*invite)(PurpleConnection *connection, int id,
512 const char *message, const char *who);
514 void (*leave)(PurpleConnection *connection, int id);
516 int (*send)(PurpleConnection *connection, int id, PurpleMessage *msg);
518 char *(*get_user_real_name)(PurpleConnection *gc, int id, const char *who);
520 void (*set_topic)(PurpleConnection *gc, int id, const char *topic);
523 #define PURPLE_PROTOCOL_HAS_CHAT_IFACE(obj) (G_TYPE_CHECK_INSTANCE_TYPE((obj), PURPLE_TYPE_PROTOCOL_CHAT_IFACE))
524 #define PURPLE_PROTOCOL_GET_CHAT_IFACE(obj) (G_TYPE_INSTANCE_GET_INTERFACE((obj), PURPLE_TYPE_PROTOCOL_CHAT_IFACE, \
525 PurpleProtocolChatIface))
527 #define PURPLE_TYPE_PROTOCOL_PRIVACY_IFACE (purple_protocol_privacy_iface_get_type())
529 typedef struct _PurpleProtocolPrivacyIface PurpleProtocolPrivacyIface;
532 * PurpleProtocolPrivacyIface:
533 * @add_permit: Add the buddy on the required authorized list.
534 * @add_deny: Add the buddy on the required blocked list.
535 * @rem_permit: Remove the buddy from the requried authorized list.
536 * @rem_deny: Remove the buddy from the required blocked list.
537 * @set_permit_deny:Update the server with the privacy information on the permit and deny lists.
539 * The protocol privacy interface.
541 * This interface provides privacy callbacks such as to permit/deny users.
543 struct _PurpleProtocolPrivacyIface
545 /*< private >*/
546 GTypeInterface parent_iface;
548 /*< public >*/
549 void (*add_permit)(PurpleConnection *gc, const char *name);
551 void (*add_deny)(PurpleConnection *gc, const char *name);
553 void (*rem_permit)(PurpleConnection *gc, const char *name);
555 void (*rem_deny)(PurpleConnection *gc, const char *name);
557 void (*set_permit_deny)(PurpleConnection *gc);
560 #define PURPLE_PROTOCOL_HAS_PRIVACY_IFACE(obj) (G_TYPE_CHECK_INSTANCE_TYPE((obj), PURPLE_TYPE_PROTOCOL_PRIVACY_IFACE))
561 #define PURPLE_PROTOCOL_GET_PRIVACY_IFACE(obj) (G_TYPE_INSTANCE_GET_INTERFACE((obj), PURPLE_TYPE_PROTOCOL_PRIVACY_IFACE, \
562 PurpleProtocolPrivacyIface))
564 #define PURPLE_TYPE_PROTOCOL_ROOMLIST_IFACE (purple_protocol_roomlist_iface_get_type())
566 typedef struct _PurpleProtocolRoomlistIface PurpleProtocolRoomlistIface;
569 * PurpleProtocolRoomlistIface:
571 * The protocol roomlist interface.
573 * This interface provides callbacks for room listing.
575 struct _PurpleProtocolRoomlistIface
577 /*< private >*/
578 GTypeInterface parent_iface;
580 /*< public >*/
581 PurpleRoomlist *(*get_list)(PurpleConnection *gc);
583 void (*cancel)(PurpleRoomlist *list);
585 void (*expand_category)(PurpleRoomlist *list,
586 PurpleRoomlistRoom *category);
588 /* room list serialize */
589 char *(*room_serialize)(PurpleRoomlistRoom *room);
592 #define PURPLE_PROTOCOL_HAS_ROOMLIST_IFACE(obj) (G_TYPE_CHECK_INSTANCE_TYPE((obj), PURPLE_TYPE_PROTOCOL_ROOMLIST_IFACE))
593 #define PURPLE_PROTOCOL_GET_ROOMLIST_IFACE(obj) (G_TYPE_INSTANCE_GET_INTERFACE((obj), PURPLE_TYPE_PROTOCOL_ROOMLIST_IFACE, \
594 PurpleProtocolRoomlistIface))
596 #define PURPLE_TYPE_PROTOCOL_MEDIA_IFACE (purple_protocol_media_iface_get_type())
598 typedef struct _PurpleProtocolMediaIface PurpleProtocolMediaIface;
601 * PurpleProtocolMediaIface:
602 * @initiate_session: Initiate a media session with the given contact.
603 * <sbr/>@account: The account to initiate the media session
604 * on.
605 * <sbr/>@who: The remote user to initiate the session with.
606 * <sbr/>@type: The type of media session to initiate.
607 * <sbr/>Returns: %TRUE if the call succeeded else %FALSE.
608 * (Doesn't imply the media session or stream
609 * will be successfully created)
610 * @get_caps: Checks to see if the given contact supports the given type of
611 * media session.
612 * <sbr/>@account: The account the contact is on.
613 * <sbr/>@who: The remote user to check for media capability with.
614 * <sbr/>Returns: The media caps the contact supports.
615 * @send_dtmf: Sends DTMF codes out-of-band in a protocol-specific way if the
616 * protocol supports it, or failing that in-band if the media backend
617 * can do so. See purple_media_send_dtmf().
619 * The protocol media interface.
621 * This interface provides callbacks for media sessions on the protocol.
623 struct _PurpleProtocolMediaIface
625 /*< private >*/
626 GTypeInterface parent_iface;
628 /*< public >*/
629 gboolean (*initiate_session)(PurpleAccount *account, const char *who,
630 PurpleMediaSessionType type);
632 PurpleMediaCaps (*get_caps)(PurpleAccount *account,
633 const char *who);
635 gboolean (*send_dtmf)(PurpleMedia *media, gchar dtmf,
636 guint8 volume, guint8 duration);
639 #define PURPLE_PROTOCOL_HAS_MEDIA_IFACE(obj) (G_TYPE_CHECK_INSTANCE_TYPE((obj), PURPLE_TYPE_PROTOCOL_MEDIA_IFACE))
640 #define PURPLE_PROTOCOL_GET_MEDIA_IFACE(obj) (G_TYPE_INSTANCE_GET_INTERFACE((obj), PURPLE_TYPE_PROTOCOL_MEDIA_IFACE, \
641 PurpleProtocolMediaIface))
643 #define PURPLE_TYPE_PROTOCOL_FACTORY_IFACE (purple_protocol_factory_iface_get_type())
645 typedef struct _PurpleProtocolFactoryIface PurpleProtocolFactoryIface;
648 * PurpleProtocolFactoryIface:
649 * @connection_new: Creates a new protocol-specific connection object that
650 * inherits #PurpleConnection.
651 * @roomlist_new: Creates a new protocol-specific room list object that
652 * inherits #PurpleRoomlist.
653 * @whiteboard_new: Creates a new protocol-specific whiteboard object that
654 * inherits #PurpleWhiteboard.
655 * @xfer_new: Creates a new protocol-specific file transfer object that
656 * inherits #PurpleXfer.
658 * The protocol factory interface.
660 * This interface provides callbacks for construction of protocol-specific
661 * subclasses of some purple objects.
663 struct _PurpleProtocolFactoryIface
665 /*< private >*/
666 GTypeInterface parent_iface;
668 /*< public >*/
669 PurpleConnection *(*connection_new)(PurpleProtocol *protocol,
670 PurpleAccount *account,
671 const char *password);
673 PurpleRoomlist *(*roomlist_new)(PurpleAccount *account);
675 PurpleWhiteboard *(*whiteboard_new)(PurpleAccount *account,
676 const char *who, int state);
679 #define PURPLE_PROTOCOL_HAS_FACTORY_IFACE(obj) (G_TYPE_CHECK_INSTANCE_TYPE((obj), PURPLE_TYPE_PROTOCOL_FACTORY_IFACE))
680 #define PURPLE_PROTOCOL_GET_FACTORY_IFACE(obj) (G_TYPE_INSTANCE_GET_INTERFACE((obj), PURPLE_TYPE_PROTOCOL_FACTORY_IFACE, \
681 PurpleProtocolFactoryIface))
684 * PURPLE_PROTOCOL_IMPLEMENTS:
685 * @protocol: The protocol in which to check
686 * @IFACE: The interface name in caps. e.g. <literal>CLIENT_IFACE</literal>
687 * @func: The function to check
689 * Returns: %TRUE if a protocol implements a function in an interface,
690 * %FALSE otherwise.
692 #define PURPLE_PROTOCOL_IMPLEMENTS(protocol, IFACE, func) \
693 (PURPLE_PROTOCOL_HAS_##IFACE(protocol) && \
694 PURPLE_PROTOCOL_GET_##IFACE(protocol)->func != NULL)
696 G_BEGIN_DECLS
698 /**************************************************************************/
699 /* Protocol Object API */
700 /**************************************************************************/
703 * purple_protocol_get_type:
705 * Returns: The #GType for #PurpleProtocol.
707 GType purple_protocol_get_type(void);
710 * purple_protocol_get_id:
711 * @protocol: The protocol.
713 * Returns the ID of a protocol.
715 * Returns: The ID of the protocol.
717 const char *purple_protocol_get_id(const PurpleProtocol *protocol);
720 * purple_protocol_get_name:
721 * @protocol: The protocol.
723 * Returns the translated name of a protocol.
725 * Returns: The translated name of the protocol.
727 const char *purple_protocol_get_name(const PurpleProtocol *protocol);
730 * purple_protocol_get_options:
731 * @protocol: The protocol.
733 * Returns the options of a protocol.
735 * Returns: The options of the protocol.
737 PurpleProtocolOptions purple_protocol_get_options(const PurpleProtocol *protocol);
740 * purple_protocol_get_user_splits:
741 * @protocol: The protocol.
743 * Returns the user splits of a protocol.
745 * Returns: (element-type PurpleAccountUserSplit) (transfer none): The user
746 * splits of the protocol.
748 GList *purple_protocol_get_user_splits(const PurpleProtocol *protocol);
751 * purple_protocol_get_account_options:
752 * @protocol: The protocol.
754 * Returns the account options for a protocol.
756 * Returns: (element-type PurpleAccountOption) (transfer none): The account
757 * options for the protocol.
759 GList *purple_protocol_get_account_options(const PurpleProtocol *protocol);
762 * purple_protocol_get_icon_spec:
763 * @protocol: The protocol.
765 * Returns the icon spec of a protocol.
767 * Returns: The icon spec of the protocol.
769 PurpleBuddyIconSpec *purple_protocol_get_icon_spec(const PurpleProtocol *protocol);
772 * purple_protocol_get_whiteboard_ops:
773 * @protocol: The protocol.
775 * Returns the whiteboard ops of a protocol.
777 * Returns: The whiteboard ops of the protocol.
779 PurpleWhiteboardOps *purple_protocol_get_whiteboard_ops(const PurpleProtocol *protocol);
782 * purple_protocol_override:
783 * @protocol: The protocol instance.
784 * @flags: What instance data to delete.
786 * Lets derived protocol types override the base type's instance data, such as
787 * protocol options, user splits, icon spec, etc.
788 * This function is called in the *_init() function of your derived protocol,
789 * to delete the parent type's data so you can define your own.
791 void purple_protocol_override(PurpleProtocol *protocol,
792 PurpleProtocolOverrideFlags flags);
794 /**************************************************************************/
795 /* Protocol Class API */
796 /**************************************************************************/
798 void purple_protocol_class_login(PurpleProtocol *protocol, PurpleAccount *account);
800 void purple_protocol_class_close(PurpleProtocol *protocol, PurpleConnection *connection);
802 GList *purple_protocol_class_status_types(PurpleProtocol *protocol,
803 PurpleAccount *account);
805 const char *purple_protocol_class_list_icon(PurpleProtocol *protocol,
806 PurpleAccount *account, PurpleBuddy *buddy);
808 /**************************************************************************/
809 /* Protocol Client Interface API */
810 /**************************************************************************/
813 * purple_protocol_client_iface_get_type:
815 * Returns: The #GType for the protocol client interface.
817 * Since: 3.0.0
819 GType purple_protocol_client_iface_get_type(void);
822 * purple_protocol_client_iface_get_actions:
823 * @protocol: The #PurpleProtocol instance.
824 * @connection: The #PurpleConnection instance.
826 * Gets a list of actions for @connection.
828 * Returns: (transfer full) (element-type PurpleProtocolAction): The list of actions for @connection.
830 * Since: 3.0.0
832 GList *purple_protocol_client_iface_get_actions(PurpleProtocol *protocol,
833 PurpleConnection *connection);
836 * purple_protocol_client_iface_list_emblem:
837 * @protocol: The #PurpleProtocol instance.
838 * @buddy: The #PurpleBuddy instance.
840 * Gets the icon name of the emblem that should be used for @buddy.
842 * Returns: The icon name of the emblem or NULL.
844 * Since: 3.0.0
846 const char *purple_protocol_client_iface_list_emblem(PurpleProtocol *protocol,
847 PurpleBuddy *buddy);
850 * purple_protocol_client_iface_status_text:
851 * @protocol: The #PurpleProtocol instance.
852 * @buddy: The #ProtocolBuddy instance.
854 * Gets the status text for @buddy.
856 * Returns: (transfer full): The status text for @buddy or NULL.
858 * Since: 3.0.0
860 char *purple_protocol_client_iface_status_text(PurpleProtocol *protocol,
861 PurpleBuddy *buddy);
864 * purple_protocol_client_iface_tooltip_text:
865 * @protocol: The #PurpleProtocol instance.
866 * @buddy: The #PurpleBuddy instance.
867 * @user_info: The #PurpleNotifyUserInfo instance.
868 * @full: Whether or not additional info should be added.
870 * Asks @protocol to update @user_info for @buddy. If @full is %TRUE then
871 * more detailed information will added.
873 * Since: 3.0.0
875 void purple_protocol_client_iface_tooltip_text(PurpleProtocol *protocol,
876 PurpleBuddy *buddy, PurpleNotifyUserInfo *user_info, gboolean full);
878 GList *purple_protocol_client_iface_blist_node_menu(PurpleProtocol *protocol,
879 PurpleBlistNode *node);
881 void purple_protocol_client_iface_buddy_free(PurpleProtocol *protocol, PurpleBuddy *buddy);
883 void purple_protocol_client_iface_convo_closed(PurpleProtocol *protocol,
884 PurpleConnection *connection, const char *who);
886 const char *purple_protocol_client_iface_normalize(PurpleProtocol *protocol,
887 const PurpleAccount *account, const char *who);
889 PurpleChat *purple_protocol_client_iface_find_blist_chat(PurpleProtocol *protocol,
890 PurpleAccount *account, const char *name);
892 gboolean purple_protocol_client_iface_offline_message(PurpleProtocol *protocol,
893 const PurpleBuddy *buddy);
895 GHashTable *purple_protocol_client_iface_get_account_text_table(PurpleProtocol *protocol,
896 PurpleAccount *account);
898 PurpleMood *purple_protocol_client_iface_get_moods(PurpleProtocol *protocol,
899 PurpleAccount *account);
901 gssize purple_protocol_client_iface_get_max_message_size(PurpleProtocol *protocol,
902 PurpleConversation *conv);
904 /**************************************************************************/
905 /* Protocol Server Interface API */
906 /**************************************************************************/
909 * purple_protocol_server_iface_get_type:
911 * Returns: The #GType for the protocol server interface.
913 GType purple_protocol_server_iface_get_type(void);
915 void purple_protocol_server_iface_register_user(PurpleProtocol *protocol,
916 PurpleAccount *account);
919 * purple_protocol_server_iface_unregister_user:
920 * @cb: (scope call):
922 void purple_protocol_server_iface_unregister_user(PurpleProtocol *protocol,
923 PurpleAccount *account, PurpleAccountUnregistrationCb cb, void *user_data);
925 void purple_protocol_server_iface_set_info(PurpleProtocol *protocol, PurpleConnection *connection,
926 const char *info);
928 void purple_protocol_server_iface_get_info(PurpleProtocol *protocol, PurpleConnection *connection,
929 const char *who);
931 void purple_protocol_server_iface_set_status(PurpleProtocol *protocol,
932 PurpleAccount *account, PurpleStatus *status);
934 void purple_protocol_server_iface_set_idle(PurpleProtocol *protocol, PurpleConnection *connection,
935 int idletime);
937 void purple_protocol_server_iface_change_passwd(PurpleProtocol *protocol,
938 PurpleConnection *connection, const char *old_pass, const char *new_pass);
940 void purple_protocol_server_iface_add_buddy(PurpleProtocol *protocol,
941 PurpleConnection *pc, PurpleBuddy *buddy, PurpleGroup *group,
942 const char *message);
944 void purple_protocol_server_iface_add_buddies(PurpleProtocol *protocol,
945 PurpleConnection *pc, GList *buddies, GList *groups,
946 const char *message);
948 void purple_protocol_server_iface_remove_buddy(PurpleProtocol *protocol,
949 PurpleConnection *connection, PurpleBuddy *buddy, PurpleGroup *group);
951 void purple_protocol_server_iface_remove_buddies(PurpleProtocol *protocol,
952 PurpleConnection *connection, GList *buddies, GList *groups);
954 void purple_protocol_server_iface_keepalive(PurpleProtocol *protocol,
955 PurpleConnection *connection);
957 int purple_protocol_server_iface_get_keepalive_interval(PurpleProtocol *protocol);
959 void purple_protocol_server_iface_alias_buddy(PurpleProtocol *protocol,
960 PurpleConnection *connection, const char *who, const char *alias);
962 void purple_protocol_server_iface_group_buddy(PurpleProtocol *protocol,
963 PurpleConnection *connection, const char *who, const char *old_group,
964 const char *new_group);
966 void purple_protocol_server_iface_rename_group(PurpleProtocol *protocol,
967 PurpleConnection *connection, const char *old_name, PurpleGroup *group,
968 GList *moved_buddies);
970 void purple_protocol_server_iface_set_buddy_icon(PurpleProtocol *protocol,
971 PurpleConnection *connection, PurpleImage *img);
973 void purple_protocol_server_iface_remove_group(PurpleProtocol *protocol,
974 PurpleConnection *gc, PurpleGroup *group);
976 int purple_protocol_server_iface_send_raw(PurpleProtocol *protocol,
977 PurpleConnection *gc, const char *buf, int len);
980 * purple_protocol_server_iface_set_public_alias:
981 * @success_cb: (scope call):
982 * @failure_cb: (scope call):
984 void purple_protocol_server_iface_set_public_alias(PurpleProtocol *protocol,
985 PurpleConnection *gc, const char *alias,
986 PurpleSetPublicAliasSuccessCallback success_cb,
987 PurpleSetPublicAliasFailureCallback failure_cb);
990 * purple_protocol_server_iface_get_public_alias:
991 * @success_cb: (scope call):
992 * @failure_cb: (scope call):
994 void purple_protocol_server_iface_get_public_alias(PurpleProtocol *protocol,
995 PurpleConnection *gc, PurpleGetPublicAliasSuccessCallback success_cb,
996 PurpleGetPublicAliasFailureCallback failure_cb);
998 /**************************************************************************/
999 /* Protocol IM Interface API */
1000 /**************************************************************************/
1003 * purple_protocol_im_iface_get_type:
1005 * Returns: The #GType for the protocol IM interface.
1007 GType purple_protocol_im_iface_get_type(void);
1009 int purple_protocol_im_iface_send(PurpleProtocol *protocol, PurpleConnection *connection,
1010 PurpleMessage *msg);
1012 unsigned int purple_protocol_im_iface_send_typing(PurpleProtocol *protocol,
1013 PurpleConnection *connection, const char *name, PurpleIMTypingState state);
1015 /**************************************************************************/
1016 /* Protocol Chat Interface API */
1017 /**************************************************************************/
1020 * purple_protocol_chat_iface_get_type:
1022 * Returns: The #GType for the protocol chat interface.
1024 * Since: 3.0.0
1026 GType purple_protocol_chat_iface_get_type(void);
1029 * purple_protocol_chat_iface_info:
1030 * @protocol: The #PurpleProtocol instance.
1031 * @connection: The #PurpleConnection instance.
1033 * Gets the list of #PurpleProtocolChatEntry's that are required to join a
1034 * multi user chat.
1036 * Returns: (transfer full) (element-type PurpleProtocolChatEntry): The list
1037 * of #PurpleProtocolChatEntry's that are used to join a chat.
1039 * Since: 3.0.0
1041 GList *purple_protocol_chat_iface_info(PurpleProtocol *protocol,
1042 PurpleConnection *connection);
1045 * purple_protocol_chat_iface_info_defaults:
1046 * @protocol: The #PurpleProtocol instance
1047 * @connection: The #PurpleConnection instance
1048 * @chat_name: The name of the chat
1050 * Returns a #GHashTable of the default protocol dependent components that will
1051 * be passed to #purple_protocol_chat_iface_join.
1053 * Returns: (transfer full) (element-type utf8 utf8): The values that will be
1054 * used to join the chat.
1056 * Since: 3.0.0
1058 GHashTable *purple_protocol_chat_iface_info_defaults(PurpleProtocol *protocol,
1059 PurpleConnection *connection, const char *chat_name);
1062 * purple_protocol_chat_iface_join:
1063 * @protocol: The #PurpleProtocol instance
1064 * @connection: The #PurpleConnection instance
1065 * @components: (element-type utf8 utf8): The protocol dependent join
1066 * components
1068 * Joins the chat described in @components.
1070 * Since: 3.0.0
1072 void purple_protocol_chat_iface_join(PurpleProtocol *protocol, PurpleConnection *connection,
1073 GHashTable *components);
1076 * purple_protocol_chat_iface_reject:
1077 * @protocol: The #PurpleProtocol instance
1078 * @connection: The #PurpleConnection instance
1079 * @components: (element-type utf8 utf8): The protocol dependent join
1080 * components
1082 * Not quite sure exactly what this does or where it's used. Please fill in
1083 * the details if you know.
1085 * Since: 3.0.0
1087 void purple_protocol_chat_iface_reject(PurpleProtocol *protocol,
1088 PurpleConnection *connection, GHashTable *components);
1091 * purple_protocol_chat_iface_get_name:
1092 * @protocol: The #PurpleProtocol instance
1093 * @components: (element-type utf8 utf8): The protocol dependent join
1094 * components
1096 * Gets the name from @components.
1098 * Returns: (transfer full): The chat name from @components.
1100 * Since: 3.0.0
1102 char *purple_protocol_chat_iface_get_name(PurpleProtocol *protocol,
1103 GHashTable *components);
1106 * purple_protocol_chat_iface_invite:
1107 * @protocol: The #PurpleProtocol instance
1108 * @connection: The #PurpleConnection instance
1109 * @id: The id of the chat
1110 * @message: The invite message
1111 * @who: The target of the invite
1113 * Sends an invite to @who with @message.
1115 * Since: 3.0.0
1117 void purple_protocol_chat_iface_invite(PurpleProtocol *protocol,
1118 PurpleConnection *connection, int id, const char *message, const char *who);
1121 * purple_protocol_chat_iface_leave:
1122 * @protocol: The #PurpleProtocol instance
1123 * @connection: The #PurpleConnection instance
1124 * @id: The id of the chat
1126 * Leaves the chat identified by @id.
1128 * Since: 3.0.0
1130 void purple_protocol_chat_iface_leave(PurpleProtocol *protocol, PurpleConnection *connection,
1131 int id);
1134 * purple_protocol_chat_iface_send:
1135 * @protocol: The #PurpleProtocol instance
1136 * @connection: The #PurpleConnection instance
1137 * @id: The id of the chat
1138 * @msg: The message to send
1140 * Sends @msg to the chat identified by @id.
1142 * Returns: 0 on success, non-zero on failure.
1144 * Since: 3.0.0
1146 int purple_protocol_chat_iface_send(PurpleProtocol *protocol, PurpleConnection *connection,
1147 int id, PurpleMessage *msg);
1150 * purple_protocol_chat_iface_get_user_real_name:
1151 * @protocol: The #PurpleProtocol instance
1152 * @gc: The #PurpleConnection instance
1153 * @id: The id of the chat
1154 * @who: The username
1156 * Gets the real name of @who.
1158 * Returns: (transfer full): The realname of @who.
1160 * Since: 3.0.0
1162 char *purple_protocol_chat_iface_get_user_real_name(PurpleProtocol *protocol,
1163 PurpleConnection *gc, int id, const char *who);
1166 * purple_protocol_chat_iface_set_topic:
1167 * @protocol: The #PurpleProtocol instance
1168 * @gc: The #PurpleConnection instance
1169 * @id: The id of the chat
1170 * @topic: The new topic
1172 * Sets the topic for the chat with id @id to @topic.
1174 * Since: 3.0.0
1176 void purple_protocol_chat_iface_set_topic(PurpleProtocol *protocol,
1177 PurpleConnection *gc, int id, const char *topic);
1179 /**************************************************************************/
1180 /* Protocol Privacy Interface API */
1181 /**************************************************************************/
1184 * purple_protocol_privacy_iface_get_type:
1186 * Returns: The #GType for the protocol privacy interface.
1188 * Since: 3.0.0
1190 GType purple_protocol_privacy_iface_get_type(void);
1193 * purple_protocol_privacy_iface_add_permit:
1194 * @protocol: The #PurpleProtocol instance.
1195 * @connection: The #PurpleConnection instance.
1196 * @name: The username to permit.
1198 * Adds a permit to the privacy settings for @connection to allow @name to
1199 * contact the user.
1201 * Since: 3.0.0
1203 void purple_protocol_privacy_iface_add_permit(PurpleProtocol *protocol,
1204 PurpleConnection *connection, const char *name);
1207 * purple_protocol_privacy_iface_add_deny:
1208 * @protocol: The #PurpleProtocol instance.
1209 * @connection: The #PurpleConnection instance.
1210 * @name: The username to deny.
1212 * Adds a deny to the privacy settings for @connection to deny @name from
1213 * contacting the user.
1215 * Since: 3.0.0
1217 void purple_protocol_privacy_iface_add_deny(PurpleProtocol *protocol,
1218 PurpleConnection *connection, const char *name);
1221 * purple_protocol_privacy_iface_rem_permit:
1222 * @protocol: The #PurpleProtocol instance.
1223 * @connection: The #PurpleConnection instance.
1224 * @name: The username to remove from the permit privacy settings.
1226 * Removes an existing permit for @name.
1228 * Since: 3.0.0
1230 void purple_protocol_privacy_iface_rem_permit(PurpleProtocol *protocol,
1231 PurpleConnection *connection, const char *name);
1234 * purple_protocol_privacy_iface_rem_deny:
1235 * @protocol: The #PurpleProtocol instance.
1236 * @connection: The #PurpleConnection instance.
1237 * @name: The username to remove from the deny privacy settings.
1239 * Removes an existing deny for @name.
1241 * Since: 3.0.0
1243 void purple_protocol_privacy_iface_rem_deny(PurpleProtocol *protocol,
1244 PurpleConnection *connection, const char *name);
1247 * purple_protocol_privacy_iface_set_permit_deny:
1248 * @protocol: The #PurpleProtocol instance.
1249 * @connection: The #PurpleConnection instance.
1251 * Forces a sync of the privacy settings with server.
1253 * Since: 3.0.0
1255 void purple_protocol_privacy_iface_set_permit_deny(PurpleProtocol *protocol,
1256 PurpleConnection *connection);
1258 /**************************************************************************/
1259 /* Protocol Roomlist Interface API */
1260 /**************************************************************************/
1263 * purple_protocol_roomlist_iface_get_type:
1265 * Returns: The #GType for the protocol roomlist interface.
1267 * Since: 3.0.0
1269 GType purple_protocol_roomlist_iface_get_type(void);
1272 * purple_protocol_roomlist_iface_get_list:
1273 * @protocol: The #PurpleProtocol instance.
1274 * @gc: The #PurpleAccount to get the roomlist for.
1276 * Gets the list of rooms for @gc.
1278 * Returns: (transfer full): The roomlist for @gc.
1280 * Since: 3.0.0
1282 PurpleRoomlist *purple_protocol_roomlist_iface_get_list(PurpleProtocol *protocol,
1283 PurpleConnection *gc);
1286 * purple_protocol_roomlist_iface_cancel:
1287 * @protocol: The #PurpleProtocol instance.
1288 * @list: The #PurpleRoomlist instance.
1290 * Requesting a roomlist can take a long time. This function cancels a request
1291 * that's already in progress.
1293 * Since: 3.0.0
1295 void purple_protocol_roomlist_iface_cancel(PurpleProtocol *protocol,
1296 PurpleRoomlist *list);
1299 * purple_protocol_roomlist_iface_expand_category:
1300 * @protocol: The #PurpleProtocol instance.
1301 * @list: The #PurpleRoomlist instance.
1302 * @category: The category to expand.
1304 * Expands the given @category for @list.
1306 * Since: 3.0.0
1308 void purple_protocol_roomlist_iface_expand_category(PurpleProtocol *protocol,
1309 PurpleRoomlist *list, PurpleRoomlistRoom *category);
1312 * purple_protocol_roomlist_iface_room_serialize:
1313 * @protocol: The #PurpleProtocol instance.
1314 * @room: The #PurpleRoomlistRoom instance.
1316 * Serializes @room into a string that will be displayed in a user interface.
1318 * Returns: (transfer full): The serialized form of @room.
1320 * Since: 3.0.0
1322 char *purple_protocol_roomlist_iface_room_serialize(PurpleProtocol *protocol,
1323 PurpleRoomlistRoom *room);
1325 /**************************************************************************/
1326 /* Protocol Media Interface API */
1327 /**************************************************************************/
1330 * purple_protocol_media_iface_get_type:
1332 * Returns: The #GType for the protocol media interface.
1334 * Since: 3.0.0
1336 GType purple_protocol_media_iface_get_type(void);
1339 * purple_protocol_media_iface_initiate_session:
1340 * @protocol: The #PurpleProtocol instance.
1341 * @account: The #PurpleAccount instance.
1342 * @who: The user to initiate a media session with.
1343 * @type: The type of media session to create.
1345 * Initiates a media connection of @type to @who.
1347 * Returns: TRUE if successful, FALSE otherwise.
1349 * Since: 3.0.0
1351 gboolean purple_protocol_media_iface_initiate_session(PurpleProtocol *protocol,
1352 PurpleAccount *account, const char *who, PurpleMediaSessionType type);
1355 * purple_protocol_media_iface_get_caps:
1356 * @protocol: The #PurpleProtocol instance.
1357 * @account: The #PurpleAccount instance.
1358 * @who: The user to get the media capabilites for.
1360 * Gets the #PurpleMediaCaps for @who which determine what types of media are
1361 * available.
1363 * Returns: the media capabilities of @who.
1365 * Since: 3.0.0
1367 PurpleMediaCaps purple_protocol_media_iface_get_caps(PurpleProtocol *protocol,
1368 PurpleAccount *account, const char *who);
1371 * purple_protocol_media_iface_send_dtmf:
1372 * @protocol: The #PurpleProtocol instance.
1373 * @media: The #PurpleMedia instance.
1374 * @dtmf: A DTMF to send.
1375 * @volume: The volume to send @dtmf at.
1376 * @duration: The duration to send @dtmf (in ms?)
1378 * Sends a DTMF (dual-tone multi-frequency) signal via the established @media
1379 * for the given @duration at the given @volume.
1381 * It is up to the specific implementation if DTMF is send in or out of band.
1383 * Returns: TRUE if successful, FALSE otherwise.
1385 * Since: 3.0.0
1387 gboolean purple_protocol_media_iface_send_dtmf(PurpleProtocol *protocol,
1388 PurpleMedia *media, gchar dtmf, guint8 volume, guint8 duration);
1390 /**************************************************************************/
1391 /* Protocol Factory Interface API */
1392 /**************************************************************************/
1395 * purple_protocol_factory_iface_get_type:
1397 * Returns: The #GType for the protocol factory interface.
1399 GType purple_protocol_factory_iface_get_type(void);
1402 * purple_protocol_factory_iface_connection_new: (skip)
1404 PurpleConnection *purple_protocol_factory_iface_connection_new(PurpleProtocol *protocol,
1405 PurpleAccount *account, const char *password);
1408 * purple_protocol_factory_iface_roomlist_new: (skip)
1410 PurpleRoomlist *purple_protocol_factory_iface_roomlist_new(PurpleProtocol *protocol,
1411 PurpleAccount *account);
1414 * purple_protocol_factory_iface_whiteboard_new: (skip)
1416 PurpleWhiteboard *purple_protocol_factory_iface_whiteboard_new(PurpleProtocol *protocol,
1417 PurpleAccount *account, const char *who, int state);
1419 G_END_DECLS
1421 #endif /* PURPLE_PROTOCOL_H */