comparison: libpurple/purpleprotocol.h
libpurple/purpleprotocol.h
- changeset 41155
- 922c9e70900c
- parent 41037
- c2043b9692f6
- child 41205
- c5513eb740aa
equal
deleted
inserted
replaced
| 41154:862153de4f30 | 41155:922c9e70900c |
|---|---|
| 1 /* | |
| 2 * Purple - Internet Messaging Library | |
| 3 * Copyright (C) Pidgin Developers <devel@pidgin.im> | |
| 4 * | |
| 5 * Purple is the legal property of its developers, whose names are too numerous | |
| 6 * to list here. Please refer to the COPYRIGHT file distributed with this | |
| 7 * source distribution. | |
| 8 * | |
| 9 * This program is free software; you can redistribute it and/or modify | |
| 10 * it under the terms of the GNU General Public License as published by | |
| 11 * the Free Software Foundation; either version 2 of the License, or | |
| 12 * (at your option) any later version. | |
| 13 * | |
| 14 * This program is distributed in the hope that it will be useful, | |
| 15 * but WITHOUT ANY WARRANTY; without even the implied warranty of | |
| 16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
| 17 * GNU General Public License for more details. | |
| 18 * | |
| 19 * You should have received a copy of the GNU General Public License | |
| 20 * along with this program; if not, see <https://www.gnu.org/licenses/>. | |
| 21 */ | |
| 22 | |
| 23 #if !defined(PURPLE_GLOBAL_HEADER_INSIDE) && !defined(PURPLE_COMPILATION) | |
| 24 # error "only <purple.h> may be included directly" | |
| 25 #endif | |
| 26 | |
| 27 #ifndef PURPLE_PROTOCOL_H | |
| 28 #define PURPLE_PROTOCOL_H | |
| 29 | |
| 30 #include <glib.h> | |
| 31 #include <glib-object.h> | |
| 32 | |
| 33 /** | |
| 34 * SECTION:protocol | |
| 35 * @section_id: libpurple-protocol | |
| 36 * @short_description: <filename>protocol.h</filename> | |
| 37 * @title: Protocol Object and Interfaces | |
| 38 * | |
| 39 * #PurpleProtocol is the base type for all protocols in libpurple. | |
| 40 */ | |
| 41 | |
| 42 /** | |
| 43 * PURPLE_TYPE_PROTOCOL: | |
| 44 * | |
| 45 * The standard _TYPE_ macro for #PurpleProtocol. | |
| 46 * | |
| 47 * Since: 3.0.0 | |
| 48 */ | |
| 49 #define PURPLE_TYPE_PROTOCOL (purple_protocol_get_type()) | |
| 50 | |
| 51 /** | |
| 52 * purple_protocol_get_type: | |
| 53 * | |
| 54 * Gets the #GType for #PurpleProtocol. | |
| 55 * | |
| 56 * Returns: The #GType of #PurpleProtocol. | |
| 57 * | |
| 58 * Since: 3.0.0 | |
| 59 */ | |
| 60 | |
| 61 G_DECLARE_DERIVABLE_TYPE(PurpleProtocol, purple_protocol, PURPLE, PROTOCOL, | |
| 62 GObject) | |
| 63 | |
| 64 #include "account.h" | |
| 65 #include "buddyicon.h" | |
| 66 #include "connection.h" | |
| 67 #include "image.h" | |
| 68 #include "purpleaccountoption.h" | |
| 69 #include "purpleaccountusersplit.h" | |
| 70 #include "purplemessage.h" | |
| 71 #include "purplewhiteboardops.h" | |
| 72 #include "status.h" | |
| 73 | |
| 74 /** | |
| 75 * PurpleProtocolOptions: | |
| 76 * @OPT_PROTO_UNIQUE_CHATNAME: User names are unique to a chat and are not | |
| 77 * shared between rooms.<sbr/> | |
| 78 * XMPP lets you choose what name you want in chats, so it shouldn't | |
| 79 * be pulling the aliases from the buddy list for the chat list; it | |
| 80 * gets annoying. | |
| 81 * @OPT_PROTO_CHAT_TOPIC: Chat rooms have topics.<sbr/> | |
| 82 * IRC and XMPP support this. | |
| 83 * @OPT_PROTO_NO_PASSWORD: Don't require passwords for sign-in.<sbr/> | |
| 84 * Zephyr doesn't require passwords, so there's no need for a | |
| 85 * password prompt. | |
| 86 * @OPT_PROTO_MAIL_CHECK: Notify on new mail.<sbr/> | |
| 87 * MSN and Yahoo notify you when you have new mail. | |
| 88 * @OPT_PROTO_PASSWORD_OPTIONAL: Allow passwords to be optional.<sbr/> | |
| 89 * Passwords in IRC are optional, and are needed for certain | |
| 90 * functionality. | |
| 91 * @OPT_PROTO_USE_POINTSIZE: Allows font size to be specified in sane point | |
| 92 * size.<sbr/> | |
| 93 * Probably just XMPP and Y!M | |
| 94 * @OPT_PROTO_REGISTER_NOSCREENNAME: Set the Register button active even when | |
| 95 * the username has not been specified.<sbr/> | |
| 96 * Gadu-Gadu doesn't need a username to register new account (because | |
| 97 * usernames are assigned by the server). | |
| 98 * @OPT_PROTO_SLASH_COMMANDS_NATIVE: Indicates that slash commands are native | |
| 99 * to this protocol.<sbr/> | |
| 100 * Used as a hint that unknown commands should not be sent as | |
| 101 * messages. | |
| 102 * @OPT_PROTO_INVITE_MESSAGE: Indicates that this protocol supports sending a | |
| 103 * user-supplied message along with an invitation. | |
| 104 * @OPT_PROTO_AUTHORIZATION_GRANTED_MESSAGE: Indicates that this protocol | |
| 105 * supports sending a user-supplied message along with an | |
| 106 * authorization acceptance. | |
| 107 * @OPT_PROTO_AUTHORIZATION_DENIED_MESSAGE: Indicates that this protocol | |
| 108 * supports sending a user-supplied message along with an | |
| 109 * authorization denial. | |
| 110 * | |
| 111 * Protocol options | |
| 112 * | |
| 113 * These should all be stuff that some protocols can do and others can't. | |
| 114 */ | |
| 115 typedef enum /*< flags >*/ | |
| 116 { | |
| 117 OPT_PROTO_UNIQUE_CHATNAME = 0x00000004, | |
| 118 OPT_PROTO_CHAT_TOPIC = 0x00000008, | |
| 119 OPT_PROTO_NO_PASSWORD = 0x00000010, | |
| 120 OPT_PROTO_MAIL_CHECK = 0x00000020, | |
| 121 OPT_PROTO_PASSWORD_OPTIONAL = 0x00000080, | |
| 122 OPT_PROTO_USE_POINTSIZE = 0x00000100, | |
| 123 OPT_PROTO_REGISTER_NOSCREENNAME = 0x00000200, | |
| 124 OPT_PROTO_SLASH_COMMANDS_NATIVE = 0x00000400, | |
| 125 OPT_PROTO_INVITE_MESSAGE = 0x00000800, | |
| 126 OPT_PROTO_AUTHORIZATION_GRANTED_MESSAGE = 0x00001000, | |
| 127 OPT_PROTO_AUTHORIZATION_DENIED_MESSAGE = 0x00002000 | |
| 128 | |
| 129 } PurpleProtocolOptions; | |
| 130 | |
| 131 /** | |
| 132 * PurpleProtocol: | |
| 133 * | |
| 134 * Represents an instance of a protocol registered with #PurpleProtocolManager. | |
| 135 * | |
| 136 * Since: 3.0.0 | |
| 137 */ | |
| 138 | |
| 139 /** | |
| 140 * PurpleProtocolClass: | |
| 141 * @get_user_splits: Returns a list of all #PurpleAccountUserSplit's that the | |
| 142 * procotol provides. | |
| 143 * @get_account_options: Returns a list of all #PurpleAccountOption's for the | |
| 144 * protocol. | |
| 145 * @get_buddy_icon_spec: Returns a #PurpleBuddyIconSpec that should be used. | |
| 146 * @get_whiteboard_ops: Return the #PurpleWhiteboardOps that should be used. | |
| 147 * @login: Logs into the server. | |
| 148 * @close: Close sconnection with the server. | |
| 149 * @status_types: Returns a list of #PurpleStatusType which exist for this | |
| 150 * account; and must add at least the offline and online states. | |
| 151 * @list_icon: Returns the base icon name for the given buddy and account. If | |
| 152 * buddy is %NULL and the account is non-%NULL, it will return the | |
| 153 * name to use for the account's icon. If both are %NULL, it will | |
| 154 * return the name to use for the protocol's icon. | |
| 155 * | |
| 156 * The base class for all protocols. | |
| 157 * | |
| 158 * All protocol types must implement the methods in this class. | |
| 159 * | |
| 160 * Since: 3.0.0 | |
| 161 */ | |
| 162 struct _PurpleProtocolClass { | |
| 163 GObjectClass parent_class; | |
| 164 | |
| 165 GList *(*get_user_splits)(PurpleProtocol *protocol); | |
| 166 GList *(*get_account_options)(PurpleProtocol *protocol); | |
| 167 PurpleBuddyIconSpec *(*get_buddy_icon_spec)(PurpleProtocol *protocol); | |
| 168 PurpleWhiteboardOps *(*get_whiteboard_ops)(PurpleProtocol *protocol); | |
| 169 | |
| 170 void (*login)(PurpleAccount *account); | |
| 171 | |
| 172 void (*close)(PurpleConnection *connection); | |
| 173 | |
| 174 GList *(*status_types)(PurpleAccount *account); | |
| 175 | |
| 176 const gchar *(*list_icon)(PurpleAccount *account, PurpleBuddy *buddy); | |
| 177 | |
| 178 /*< private >*/ | |
| 179 gpointer reserved[4]; | |
| 180 }; | |
| 181 | |
| 182 /** | |
| 183 * PURPLE_PROTOCOL_IMPLEMENTS: | |
| 184 * @protocol: The protocol in which to check | |
| 185 * @IFACE: The interface name in caps. e.g. <literal>CLIENT</literal> | |
| 186 * @func: The function to check | |
| 187 * | |
| 188 * Returns: %TRUE if a protocol implements a function in an interface, | |
| 189 * %FALSE otherwise. | |
| 190 * | |
| 191 * Since: 3.0.0 | |
| 192 */ | |
| 193 #define PURPLE_PROTOCOL_IMPLEMENTS(protocol, IFACE, func) \ | |
| 194 (PURPLE_IS_PROTOCOL_##IFACE(protocol) && \ | |
| 195 PURPLE_PROTOCOL_##IFACE##_GET_IFACE(protocol)->func != NULL) | |
| 196 | |
| 197 G_BEGIN_DECLS | |
| 198 | |
| 199 /** | |
| 200 * purple_protocol_get_id: | |
| 201 * @protocol: The #PurpleProtocol instance. | |
| 202 * | |
| 203 * Gets the ID of a protocol. | |
| 204 * | |
| 205 * Returns: The ID of the protocol. | |
| 206 * | |
| 207 * Since: 3.0.0 | |
| 208 */ | |
| 209 const gchar *purple_protocol_get_id(PurpleProtocol *protocol); | |
| 210 | |
| 211 /** | |
| 212 * purple_protocol_get_name: | |
| 213 * @protocol: The #PurpleProtocol instance. | |
| 214 * | |
| 215 * Gets the translated name of a protocol. | |
| 216 * | |
| 217 * Returns: The translated name of the protocol. | |
| 218 * | |
| 219 * Since: 3.0.0 | |
| 220 */ | |
| 221 const gchar *purple_protocol_get_name(PurpleProtocol *protocol); | |
| 222 | |
| 223 /** | |
| 224 * purple_protocol_get_description: | |
| 225 * @protocol: The #PurpleProtocol instance. | |
| 226 * | |
| 227 * Gets the description of a protocol. | |
| 228 * | |
| 229 * Returns: The Description of the protocol. | |
| 230 * | |
| 231 * Since: 3.0.0 | |
| 232 */ | |
| 233 const gchar *purple_protocol_get_description(PurpleProtocol *protocol); | |
| 234 | |
| 235 /** | |
| 236 * purple_protocol_get_options: | |
| 237 * @protocol: The #PurpleProtocol instance. | |
| 238 * | |
| 239 * Gets the options of a protocol. | |
| 240 * | |
| 241 * Returns: The options of the protocol. | |
| 242 * | |
| 243 * Since: 3.0.0 | |
| 244 */ | |
| 245 PurpleProtocolOptions purple_protocol_get_options(PurpleProtocol *protocol); | |
| 246 | |
| 247 /** | |
| 248 * purple_protocol_get_user_splits: | |
| 249 * @protocol: The #PurpleProtocol instance. | |
| 250 * | |
| 251 * Gets the user splits of a protocol. | |
| 252 * | |
| 253 * Returns: (element-type PurpleAccountUserSplit) (transfer full): The user | |
| 254 * splits of the protocol. | |
| 255 * | |
| 256 * Since: 3.0.0 | |
| 257 */ | |
| 258 GList *purple_protocol_get_user_splits(PurpleProtocol *protocol); | |
| 259 | |
| 260 /** | |
| 261 * purple_protocol_get_account_options: | |
| 262 * @protocol: The #PurpleProtocol instance. | |
| 263 * | |
| 264 * Gets the account options for a protocol. | |
| 265 * | |
| 266 * Returns: (element-type PurpleAccountOption) (transfer full): The account | |
| 267 * options for the protocol. | |
| 268 * | |
| 269 * Since: 3.0.0 | |
| 270 */ | |
| 271 GList *purple_protocol_get_account_options(PurpleProtocol *protocol); | |
| 272 | |
| 273 /** | |
| 274 * purple_protocol_get_icon_spec: | |
| 275 * @protocol: The #PurpleProtocol instance. | |
| 276 * | |
| 277 * Gets the icon spec of a protocol. | |
| 278 * | |
| 279 * Returns: (transfer full): The icon spec of the protocol. | |
| 280 * | |
| 281 * Since: 3.0.0 | |
| 282 */ | |
| 283 PurpleBuddyIconSpec *purple_protocol_get_icon_spec(PurpleProtocol *protocol); | |
| 284 | |
| 285 /** | |
| 286 * purple_protocol_get_whiteboard_ops: | |
| 287 * @protocol: The #PurpleProtocol instance. | |
| 288 * | |
| 289 * Gets the whiteboard ops of a protocol. | |
| 290 * | |
| 291 * Returns: (transfer none): The whiteboard ops of the protocol. | |
| 292 * | |
| 293 * Since: 3.0.0 | |
| 294 */ | |
| 295 PurpleWhiteboardOps *purple_protocol_get_whiteboard_ops(PurpleProtocol *protocol); | |
| 296 | |
| 297 /** | |
| 298 * purple_protocol_login: | |
| 299 * @protocol: The #PurpleProtocol instance. | |
| 300 * @account: The #PurpleAccount to login. | |
| 301 * | |
| 302 * Logs @account in using @protocol. | |
| 303 * | |
| 304 * Since: 3.0.0 | |
| 305 */ | |
| 306 void purple_protocol_login(PurpleProtocol *protocol, PurpleAccount *account); | |
| 307 | |
| 308 /** | |
| 309 * purple_protocol_close: | |
| 310 * @protocol: The #PurpleProtocol instance. | |
| 311 * @connection: The #PurpleConnection to close. | |
| 312 * | |
| 313 * Closes @connection using @protocol. | |
| 314 * | |
| 315 * Since: 3.0.0 | |
| 316 */ | |
| 317 void purple_protocol_close(PurpleProtocol *protocol, PurpleConnection *connection); | |
| 318 | |
| 319 /** | |
| 320 * purple_protocol_get_status_types: | |
| 321 * @protocol: The #PurpleProtocol instance. | |
| 322 * @account: The #PurpleAccount instance. | |
| 323 * | |
| 324 * Gets all of the #PurpleStatusType's for @account which uses @protocol. | |
| 325 * | |
| 326 * Returns: (transfer full) (element-type PurpleStatusType): A list of the | |
| 327 * available PurpleStatusType's for @account with @protocol. | |
| 328 * | |
| 329 * Since: 3.0.0 | |
| 330 */ | |
| 331 GList *purple_protocol_get_status_types(PurpleProtocol *protocol, PurpleAccount *account); | |
| 332 | |
| 333 /** | |
| 334 * purple_protocol_get_list_icon: | |
| 335 * @protocol: The #PurpleProtocol instance. | |
| 336 * @account: The #PurpleAccount instance. | |
| 337 * @buddy: The #PurpleBuddy instance. | |
| 338 * | |
| 339 * Gets the icon to show in the contact list for @buddy on @account which uses | |
| 340 * @protocol. | |
| 341 * | |
| 342 * Both @account and @buddy may be %NULL to get the default icon for @protocol. | |
| 343 * | |
| 344 * Returns: The name of the icon file to use in the contact list for @buddy. | |
| 345 * | |
| 346 * Since: 3.0.0 | |
| 347 */ | |
| 348 const gchar *purple_protocol_get_list_icon(PurpleProtocol *protocol, PurpleAccount *account, PurpleBuddy *buddy); | |
| 349 | |
| 350 /** | |
| 351 * purple_protocol_get_icon_name: | |
| 352 * @protocol: The #PurpleProtocol instance. | |
| 353 * | |
| 354 * Gets the name of the icon that the protocol made available via either | |
| 355 * purple_protocol_get_icon_search_path() or | |
| 356 * purple_protocol_get_resource_path(). | |
| 357 * | |
| 358 * Returns: The name of the icon for @protocol. | |
| 359 * | |
| 360 * Since: 3.0.0 | |
| 361 */ | |
| 362 const gchar *purple_protocol_get_icon_name(PurpleProtocol *protocol); | |
| 363 | |
| 364 /** | |
| 365 * purple_protocol_get_icon_search_path: | |
| 366 * @protocol: The #PurpleProtocol instance. | |
| 367 * | |
| 368 * Gets the icon search path for @protocol. This is used to allow protocol | |
| 369 * plugins to install their icons in any XDG icon theme compliant directory. | |
| 370 * The returned value should be the path of where the icons are on disk. See | |
| 371 * gtk_icon_theme_add_search_path() for additional information. | |
| 372 * | |
| 373 * User interfaces will look for icons in this path named | |
| 374 * %chat-<protocol-name> where protocol-name is the name property of @protocol. | |
| 375 * | |
| 376 * Returns: The file system path where the icons can be found. | |
| 377 * | |
| 378 * Since: 3.0.0 | |
| 379 */ | |
| 380 const gchar *purple_protocol_get_icon_search_path(PurpleProtocol *protocol); | |
| 381 | |
| 382 /** | |
| 383 * purple_protocol_get_icon_resource_path: | |
| 384 * @protocol: The #PurpleProtocol instance. | |
| 385 * | |
| 386 * Gets the icon resource path for @protocol. This is used to make icons that | |
| 387 * have been embedded into a plugin available to libpurple. The returned value | |
| 388 * should be the path of where the icons are in the resource. See | |
| 389 * gtk_icon_theme_add_resource_path() for additional information. | |
| 390 * | |
| 391 * User interfaces will look for icons in this path named | |
| 392 * %chat-<protocol-name> where protocol-name is the name property of @protocol. | |
| 393 * | |
| 394 * Returns: The gresource path where the icons can be found. | |
| 395 * | |
| 396 * Since: 3.0.0 | |
| 397 */ | |
| 398 const gchar *purple_protocol_get_icon_resource_path(PurpleProtocol *protocol); | |
| 399 | |
| 400 G_END_DECLS | |
| 401 | |
| 402 #endif /* PURPLE_PROTOCOL_H */ |
