libpurple/protocols/facebook/api.h

   1 /* purple
   2  *
   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.
   6  *
   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.
  11  *
  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.
  16  *
  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
  20  */
  21
  22 #ifndef PURPLE_FACEBOOK_API_H
  23 #define PURPLE_FACEBOOK_API_H
  24
  25 /**
  26  * SECTION:api
  27  * @section_id: facebook-api
  28  * @short_description: <filename>api.h</filename>
  29  * @title: Facebook API
  30  *
  31  * The API for interacting with the Facebook Messenger protocol.
  32  */
  33
  34 #include "internal.h"
  35
  36 #include <glib.h>
  37
  38 #include "connection.h"
  39
  40 #include "http.h"
  41 #include "id.h"
  42 #include "mqtt.h"
  43
  44 #define FB_TYPE_API  fb_api_get_type()
  45
  46 /**
  47  * FB_API_AHOST:
  48  *
  49  * The HTTP host for the Facebook API.
  50  */
  51 #define FB_API_AHOST  "https://api.facebook.com"
  52
  53 /**
  54  * FB_API_BHOST:
  55  *
  56  * The HTTP host for the Facebook BAPI.
  57  */
  58 #define FB_API_BHOST  "https://b-api.facebook.com"
  59
  60 /**
  61  * FB_API_GHOST:
  62  *
  63  * The HTTP host for the Facebook Graph API.
  64  */
  65 #define FB_API_GHOST  "https://graph.facebook.com"
  66
  67 /**
  68  * FB_API_WHOST:
  69  *
  70  * The HTTP host for the Facebook website.
  71  */
  72 #define FB_API_WHOST  "https://www.facebook.com"
  73
  74 /**
  75  * FB_API_FBRPC_PREFIX
  76  *
  77  * The fbrpc URL prefix used in links shared from the mobile app.
  78  */
  79 #define FB_API_FBRPC_PREFIX "fbrpc://facebook/nativethirdparty"
  80
  81 /**
  82  * FB_API_KEY:
  83  *
  84  * The Facebook API key.
  85  */
  86 #define FB_API_KEY  "256002347743983"
  87
  88 /**
  89  * FB_API_SECRET:
  90  *
  91  * The Facebook API secret.
  92  */
  93 #define FB_API_SECRET  "374e60f8b9bb6b8cbb30f78030438895"
  94
  95 /**
  96  * FB_ORCA_AGENT
  97  *
  98  * The part of the user agent that looks like the official client, since the
  99  * server started checking this.
 100  */
 101
 102 #define FB_ORCA_AGENT "[FBAN/Orca-Android;FBAV/109.0.0.17.70;FBPN/com.facebook.orca;FBLC/en_US;FBBV/52182662]"
 103
 104 /**
 105  * FB_API_AGENT:
 106  *
 107  * The HTTP User-Agent header.
 108  */
 109 #define FB_API_AGENT  "Facebook plugin / Purple / 0.9.5 " FB_ORCA_AGENT
 110
 111 /**
 112  * FB_API_MQTT_AGENT
 113  *
 114  * The client information string sent in the MQTT CONNECT message
 115  */
 116
 117 #define FB_API_MQTT_AGENT FB_API_AGENT
 118
 119 /**
 120  * FB_API_URL_ATTACH:
 121  *
 122  * The URL for attachment URL requests.
 123  */
 124 #define FB_API_URL_ATTACH  FB_API_AHOST "/method/messaging.getAttachment"
 125 //#define FB_API_URL_ATTACH  FB_API_AHOST "/method/messaging.attachmentRedirect"
 126
 127 /**
 128  * FB_API_URL_AUTH:
 129  *
 130  * The URL for authentication requests.
 131  */
 132 #define FB_API_URL_AUTH  FB_API_BHOST "/method/auth.login"
 133
 134 /**
 135  * FB_API_URL_GQL:
 136  *
 137  * The URL for GraphQL requests.
 138  */
 139 #define FB_API_URL_GQL  FB_API_GHOST "/graphql"
 140
 141 /**
 142  * FB_API_URL_MESSAGES:
 143  *
 144  * The URL for linking message threads.
 145  */
 146 #define FB_API_URL_MESSAGES  FB_API_WHOST "/messages"
 147
 148 /**
 149  * FB_API_URL_PARTS:
 150  *
 151  * The URL for participant management requests.
 152  */
 153 #define FB_API_URL_PARTS  FB_API_GHOST "/participants"
 154
 155 /**
 156  * FB_API_URL_THREADS:
 157  *
 158  * The URL for thread management requests.
 159  */
 160 #define FB_API_URL_THREADS  FB_API_GHOST "/me/group_threads"
 161
 162 /**
 163  * FB_API_URL_TOPIC:
 164  *
 165  * The URL for thread topic requests.
 166  */
 167 #define FB_API_URL_TOPIC  FB_API_AHOST "/method/messaging.setthreadname"
 168
 169 /**
 170  * FB_API_QUERY_CONTACT:
 171  *
 172  * The query hash for the `UsersQuery`.
 173  *
 174  * Key mapping:
 175  *   0: user_fbids
 176  *   1: include_full_user_info
 177  *   2: profile_pic_large_size
 178  *   3: profile_pic_medium_size
 179  *   4: profile_pic_small_size
 180  */
 181 #define FB_API_QUERY_CONTACT  10153915107411729
 182
 183 /**
 184  * FB_API_QUERY_CONTACTS:
 185  *
 186  * The query hash for the `FetchContactsFullQuery`.
 187  *
 188  * Key mapping:
 189  *   0: profile_types
 190  *   1: limit
 191  *   2: big_img_size
 192  *   3: huge_img_size
 193  *   4: small_img_size
 194  */
 195 #define FB_API_QUERY_CONTACTS  10154444360806729
 196
 197 /**
 198  * FB_API_QUERY_CONTACTS_AFTER:
 199  *
 200  * The query hash for the `FetchContactsFullWithAfterQuery`.
 201  *
 202  * Key mapping:
 203  *   0: profile_types
 204  *   1: after
 205  *   2: limit
 206  *   3: big_img_size
 207  *   4: huge_img_size
 208  *   5: small_img_size
 209  */
 210 #define FB_API_QUERY_CONTACTS_AFTER  10154444360816729
 211
 212
 213 /**
 214  * FB_API_QUERY_CONTACTS_DELTA:
 215  *
 216  * The query hash for the `FetchContactsDeltaQuery`.
 217  *
 218  * Key mapping:
 219  *   0: after
 220  *   1: profile_types
 221  *   2: limit
 222  *   3: big_img_size
 223  *   4: huge_img_size
 224  *   5: small_img_size
 225  */
 226 #define FB_API_QUERY_CONTACTS_DELTA  10154444360801729
 227
 228 /**
 229  * FB_API_QUERY_STICKER:
 230  *
 231  * The query hash for the `FetchStickersWithPreviewsQuery`.
 232  *
 233  * Key mapping:
 234  *   0: sticker_ids
 235  *   1: media_type
 236  *   2: preview_size
 237  *   3: scaling_factor
 238  *   4: animated_media_type
 239  */
 240 #define FB_API_QUERY_STICKER  10152877994321729
 241
 242 /**
 243  * FB_API_QUERY_THREAD:
 244  *
 245  * The query hash for the `ThreadQuery`.
 246  *
 247  * Key mapping:
 248  *   0: thread_ids
 249  *   1: verification_type
 250  *   2: hash_key
 251  *   3: small_preview_size
 252  *   4: large_preview_size
 253  *   5: item_count
 254  *   6: event_count
 255  *   7: full_screen_height
 256  *   8: full_screen_width
 257  *   9: medium_preview_size
 258  *   10: fetch_users_separately
 259  *   11: include_message_info
 260  *   12: msg_count
 261  *   13: include_full_user_info
 262  *   14: profile_pic_large_size
 263  *   15: profile_pic_medium_size
 264  *   16: profile_pic_small_size
 265  */
 266 #define FB_API_QUERY_THREAD  10153919752036729
 267
 268 /**
 269  * FB_API_QUERY_THREADS:
 270  *
 271  * The query hash for the `ThreadListQuery`.
 272  *
 273  * Key mapping:
 274  *   0: folder_tag
 275  *   1: thread_count
 276  *   2: include_thread_info
 277  *   3: verification_type
 278  *   4: hash_key
 279  *   5: small_preview_size
 280  *   6: large_preview_size
 281  *   7: item_count
 282  *   8: event_count
 283  *   9: full_screen_height
 284  *   10: full_screen_width
 285  *   11: medium_preview_size
 286  *   12: fetch_users_separately
 287  *   13: include_message_info
 288  *   14: msg_count
 289  *   15: UNKNOWN
 290  *   16: profile_pic_large_size
 291  *   17: profile_pic_medium_size
 292  *   18: profile_pic_small_size
 293  */
 294 #define FB_API_QUERY_THREADS  10153919752026729
 295
 296 /**
 297  * FB_API_QUERY_SEQ_ID:
 298  *
 299  * A variant of ThreadListQuery with sequence ID
 300  *
 301  * TODO: parameters.
 302  */
 303
 304 #define FB_API_QUERY_SEQ_ID  10155268192741729
 305
 306 /**
 307  * FB_API_QUERY_XMA:
 308  *
 309  * The query hash for the `XMAQuery`.
 310  *
 311  * Key mapping:
 312  *   0: xma_id
 313  */
 314 #define FB_API_QUERY_XMA  10153919431161729
 315
 316 /**
 317  * FB_API_CONTACTS_COUNT:
 318  *
 319  * The maximum amount of contacts to fetch in a single request. If this
 320  * value is set too high, HTTP request will fail. This is due to the
 321  * request data being too large.
 322  */
 323 #define FB_API_CONTACTS_COUNT  500
 324
 325 /**
 326  * FB_API_TCHK:
 327  * @e: The expression.
 328  *
 329  * Checks the Thrift related expression to ensure that it evaluates to
 330  * #TRUE. If the expression evaluates to #FALSE, a #GError is assigned
 331  * to the local `error` variable, then returns with no value.
 332  *
 333  * This macro is meant to only be used for Thrift related expressions,
 334  * where the calling function has a `void` return type. This macro also
 335  * requires the existence of a predefined `error` variable, which is a
 336  * pointer of a pointer to a #GError.
 337  */
 338 #define FB_API_TCHK(e) \
 339         G_STMT_START { \
 340                 if (G_UNLIKELY(!(e))) { \
 341                         g_set_error(error, FB_API_ERROR, FB_API_ERROR_GENERAL, \
 342                                                 "Failed to read thrift: %s:%d " \
 343                                                 "%s: assertion '%s' failed", \
 344                                                 __FILE__, __LINE__, G_STRFUNC, #e); \
 345                         return; \
 346                 } \
 347         } G_STMT_END
 348
 349 /**
 350  * FB_API_MSGID:
 351  * @m: The time in milliseconds.
 352  * @i: The random integer.
 353  *
 354  * Creates a 64-bit message identifier in the Facebook format.
 355  *
 356  * Returns: The message identifier.
 357  */
 358 #define FB_API_MSGID(m, i) ((guint64) ( \
 359                 (((guint32) i) & 0x3FFFFF) | \
 360                 (((guint64) m) << 22) \
 361         ))
 362
 363 /**
 364  * FB_API_ERROR_EMIT:
 365  * @a: The #FbApi.
 366  * @e: The #FbApiError.
 367  * @c: The code to execute.
 368  *
 369  * Emits a #GError on behalf of the #FbApi.
 370  */
 371 #define FB_API_ERROR_EMIT(a, e, c) \
 372         G_STMT_START { \
 373                 if (G_UNLIKELY((e) != NULL)) { \
 374                         fb_api_error_emit(a, e); \
 375                         {c;} \
 376                 } \
 377         } G_STMT_END
 378
 379 /**
 380  * FB_API_ERROR:
 381  *
 382  * The #GQuark of the domain of API errors.
 383  */
 384 #define FB_API_ERROR  fb_api_error_quark()
 385
 386 typedef struct _FbApiEvent FbApiEvent;
 387 typedef struct _FbApiMessage FbApiMessage;
 388 typedef struct _FbApiPresence FbApiPresence;
 389 typedef struct _FbApiThread FbApiThread;
 390 typedef struct _FbApiTyping FbApiTyping;
 391 typedef struct _FbApiUser FbApiUser;
 392
 393 /**
 394  * FbApiError:
 395  * @FB_API_ERROR_GENERAL: General failure.
 396  * @FB_API_ERROR_AUTH: Authentication failure.
 397  * @FB_API_ERROR_QUEUE: Queue failure.
 398  * @FB_API_ERROR_NONFATAL: Other non-fatal errors.
 399  *
 400  * The error codes for the #FB_API_ERROR domain.
 401  */
 402 typedef enum
 403 {
 404         FB_API_ERROR_GENERAL,
 405         FB_API_ERROR_AUTH,
 406         FB_API_ERROR_QUEUE,
 407         FB_API_ERROR_NONFATAL
 408 } FbApiError;
 409
 410 /**
 411  * FbApiEventType:
 412  * @FB_API_EVENT_TYPE_THREAD_TOPIC: The thread topic was changed.
 413  * @FB_API_EVENT_TYPE_THREAD_USER_ADDED: A thread user was added.
 414  * @FB_API_EVENT_TYPE_THREAD_USER_REMOVED: A thread user was removed.
 415  *
 416  * The #FbApiEvent types.
 417  */
 418 typedef enum
 419 {
 420         FB_API_EVENT_TYPE_THREAD_TOPIC,
 421         FB_API_EVENT_TYPE_THREAD_USER_ADDED,
 422         FB_API_EVENT_TYPE_THREAD_USER_REMOVED
 423 } FbApiEventType;
 424
 425 /**
 426  * FbApiMessageFlags:
 427  * @FB_API_MESSAGE_FLAG_DONE: The text has been processed.
 428  * @FB_API_MESSAGE_FLAG_IMAGE: The text is a URL to an image.
 429  * @FB_API_MESSAGE_FLAG_SELF: The text is from the #FbApi user.
 430  *
 431  * The #FbApiMessage flags.
 432  */
 433 typedef enum
 434 {
 435         FB_API_MESSAGE_FLAG_DONE = 1 << 0,
 436         FB_API_MESSAGE_FLAG_IMAGE = 1 << 1,
 437         FB_API_MESSAGE_FLAG_SELF = 1 << 2
 438 } FbApiMessageFlags;
 439
 440 /**
 441  * FbApiEvent:
 442  * @type: The #FbApiEventType.
 443  * @uid: The user #FbId.
 444  * @tid: The thread #FbId.
 445  * @text: The event text.
 446  *
 447  * Represents a Facebook update event.
 448  */
 449 struct _FbApiEvent
 450 {
 451         FbApiEventType type;
 452         FbId uid;
 453         FbId tid;
 454         gchar *text;
 455 };
 456
 457 /**
 458  * FbApiMessage:
 459  * @flags: The #FbApiMessageFlags.
 460  * @uid: The user #FbId.
 461  * @tid: The thread #FbId.
 462  * @tstamp: The timestamp in milliseconds (UTC).
 463  * @text: The message text.
 464  *
 465  * Represents a Facebook user message.
 466  */
 467 struct _FbApiMessage
 468 {
 469         FbApiMessageFlags flags;
 470         FbId uid;
 471         FbId tid;
 472         gint64 tstamp;
 473         gchar *text;
 474 };
 475
 476 /**
 477  * FbApiPresence:
 478  * @uid: The user #FbId.
 479  * @active: #TRUE if the user is active, otherwise #FALSE.
 480  *
 481  * Represents a Facebook presence message.
 482  */
 483 struct _FbApiPresence
 484 {
 485         FbId uid;
 486         gboolean active;
 487 };
 488
 489 /**
 490  * FbApiThread:
 491  * @tid: The thread #FbId.
 492  * @topic: The topic.
 493  * @users: The #GSList of #FbApiUser's.
 494  *
 495  * Represents a Facebook message thread.
 496  */
 497 struct _FbApiThread
 498 {
 499         FbId tid;
 500         gchar *topic;
 501         GSList *users;
 502 };
 503
 504 /**
 505  * FbApiTyping:
 506  * @uid: The user #FbId.
 507  * @state: #TRUE if the user is typing, otherwise #FALSE.
 508  *
 509  * Represents a Facebook typing message.
 510  */
 511 struct _FbApiTyping
 512 {
 513         FbId uid;
 514         gboolean state;
 515 };
 516
 517 /**
 518  * FbApiUser:
 519  * @uid: The user #FbId.
 520  * @name: The name of the user.
 521  * @icon: The icon URL.
 522  * @csum: The checksum of @icon.
 523  *
 524  * Represents a Facebook user.
 525  */
 526 struct _FbApiUser
 527 {
 528         FbId uid;
 529         gchar *name;
 530         gchar *icon;
 531         gchar *csum;
 532 };
 533
 534 /**
 535  * fb_api_get_type:
 536  *
 537  * Returns: The #GType for an #FbApi.
 538  */
 539 G_DECLARE_FINAL_TYPE(FbApi, fb_api, FB, API, GObject)
 540
 541 /**
 542  * fb_api_error_quark:
 543  *
 544  * Gets the #GQuark of the domain of API errors.
 545  *
 546  * Returns: The #GQuark of the domain.
 547  */
 548 GQuark
 549 fb_api_error_quark(void);
 550
 551 /**
 552  * fb_api_new:
 553  * @gc: The #PurpleConnection.
 554  *
 555  * Creates a new #FbApi. The returned #FbApi should be freed with
 556  * #g_object_unref() when no longer needed.
 557  *
 558  * Returns: The new #FbApi.
 559  */
 560 FbApi *
 561 fb_api_new(PurpleConnection *gc);
 562
 563 /**
 564  * fb_api_rehash:
 565  * @api: The #FbApi.
 566  *
 567  * Rehashes and updates internal data of the #FbApi. This should be
 568  * called whenever properties are modified.
 569  */
 570 void
 571 fb_api_rehash(FbApi *api);
 572
 573 /**
 574  * fb_api_is_invisible:
 575  * @api: The #FbApi.
 576  *
 577  * Determines if the user of the #FbApi is invisible.
 578  *
 579  * Returns: #TRUE if the #FbApi user is invisible, otherwise #FALSE.
 580  */
 581 gboolean
 582 fb_api_is_invisible(FbApi *api);
 583
 584 /**
 585  * fb_api_error:
 586  * @api: The #FbApi.
 587  * @error: The #FbApiError.
 588  * @format: The format string literal.
 589  * @...: The arguments for @format.
 590  *
 591  * Emits an #FbApiError.
 592  */
 593 void
 594 fb_api_error(FbApi *api, FbApiError error, const gchar *format, ...)
 595              G_GNUC_PRINTF(3, 4);
 596
 597 /**
 598  * fb_api_error_emit:
 599  * @api: The #FbApi.
 600  * @error: The #GError.
 601  *
 602  * Emits a #GError on an #FbApiError.
 603  */
 604 void
 605 fb_api_error_emit(FbApi *api, GError *error);
 606
 607 /**
 608  * fb_api_auth:
 609  * @api: The #FbApi.
 610  * @user: The Facebook user name, email, or phone number.
 611  * @pass: The Facebook password.
 612  *
 613  * Sends an authentication request to Facebook. This will obtain
 614  * session information, which is required for all other requests.
 615  */
 616 void
 617 fb_api_auth(FbApi *api, const gchar *user, const gchar *pass);
 618
 619 /**
 620  * fb_api_contact:
 621  * @api: The #FbApi.
 622  * @uid: The user #FbId.
 623  *
 624  * Sends a contact request. This will obtain the general information of
 625  * a single contact.
 626  */
 627 void
 628 fb_api_contact(FbApi *api, FbId uid);
 629
 630 /**
 631  * fb_api_contacts:
 632  * @api: The #FbApi.
 633  *
 634  * Sends a contacts request. This will obtain a full list of detailed
 635  * contact information about the friends of the #FbApi user.
 636  */
 637 void
 638 fb_api_contacts(FbApi *api);
 639
 640 /**
 641  * fb_api_connect:
 642  * @api: The #FbApi.
 643  * @invisible: #TRUE to make the user invisible, otherwise #FALSE.
 644  *
 645  * Initializes and establishes the underlying MQTT connection.
 646  */
 647 void
 648 fb_api_connect(FbApi *api, gboolean invisible);
 649
 650 /**
 651  * fb_api_disconnect:
 652  * @api: The #FbApi.
 653  *
 654  * Closes the underlying MQTT connection.
 655  */
 656 void
 657 fb_api_disconnect(FbApi *api);
 658
 659 /**
 660  * fb_api_message:
 661  * @api: The #FbApi.
 662  * @id: The user or thread #FbId.
 663  * @thread: #TRUE if @id is a thread, otherwise #FALSE.
 664  * @text: The message text.
 665  *
 666  * Sends a message as the user of the #FbApi to a user or a thread.
 667  */
 668 void
 669 fb_api_message(FbApi *api, FbId id, gboolean thread, const gchar *text);
 670
 671 /**
 672  * fb_api_publish:
 673  * @api: The #FbApi.
 674  * @topic: The topic.
 675  * @format: The format string literal.
 676  * @...: The arguments for @format.
 677  *
 678  * Publishes an MQTT message.
 679  */
 680 void
 681 fb_api_publish(FbApi *api, const gchar *topic, const gchar *format, ...)
 682                G_GNUC_PRINTF(3, 4);
 683
 684 /**
 685  * fb_api_read:
 686  * @api: The #FbApi.
 687  * @id: The user or thread #FbId.
 688  * @thread: #TRUE if @id is a thread, otherwise #FALSE.
 689  *
 690  * Marks a message thread as read.
 691  */
 692 void
 693 fb_api_read(FbApi *api, FbId id, gboolean thread);
 694
 695 /**
 696  * fb_api_unread:
 697  * @api: The #FbApi.
 698  *
 699  * Sends an unread message request.
 700  */
 701 void
 702 fb_api_unread(FbApi *api);
 703
 704 /**
 705  * fb_api_thread:
 706  * @api: The #FbApi.
 707  * @tid: The thread #FbId.
 708  *
 709  * Sends a thread request. This will obtain the general information of
 710  * a single thread.
 711  */
 712 void
 713 fb_api_thread(FbApi *api, FbId tid);
 714
 715 /**
 716  * fb_api_thread_create:
 717  * @api: The #FbApi.
 718  * @uids: The #GSList of #FbId's.
 719  *
 720  * Sends a thread creation request. In order to create a thread, there
 721  * must be at least two other users in @uids.
 722  */
 723 void
 724 fb_api_thread_create(FbApi *api, GSList *uids);
 725
 726 /**
 727  * fb_api_thread_invite:
 728  * @api: The #FbApi.
 729  * @tid: The thread #FbId.
 730  * @uid: The user #FbId.
 731  *
 732  * Sends a thread user invitation request.
 733  */
 734 void
 735 fb_api_thread_invite(FbApi *api, FbId tid, FbId uid);
 736
 737 /**
 738  * fb_api_thread_remove:
 739  * @api: The #FbApi.
 740  * @tid: The thread #FbId.
 741  * @uid: The user #FbId.
 742  *
 743  * Sends a thread user removal request.
 744  */
 745 void
 746 fb_api_thread_remove(FbApi *api, FbId tid, FbId uid);
 747
 748 /**
 749  * fb_api_thread_topic:
 750  * @api: The #FbApi.
 751  * @tid: The thread #FbId.
 752  * @topic: The topic.
 753  *
 754  * Sends a thread topic change request.
 755  */
 756 void
 757 fb_api_thread_topic(FbApi *api, FbId tid, const gchar *topic);
 758
 759 /**
 760  * fb_api_threads:
 761  * @api: The #FbApi.
 762  *
 763  * Sends a threads request. This will obtain a full list of detailed
 764  * thread information about the threads of the #FbApi user.
 765  */
 766 void
 767 fb_api_threads(FbApi *api);
 768
 769 /**
 770  * fb_api_typing:
 771  * @api: The #FbApi.
 772  * @uid: The user #FbId.
 773  * @state: #TRUE if the #FbApi user is typing, otherwise #FALSE.
 774  *
 775  * Sends a typing state message for the user of the #FbApi.
 776  */
 777 void
 778 fb_api_typing(FbApi *api, FbId uid, gboolean state);
 779
 780 /**
 781  * fb_api_event_dup:
 782  * @event: The #FbApiEvent or #NULL.
 783  * @deep: #TRUE to duplicate allocated data, otherwise #FALSE.
 784  *
 785  * Duplicates an #FbApiEvent. If @event is #NULL, a new zero filled
 786  * #FbApiEvent is returned. The returned #FbApiEvent should be freed
 787  * with #fb_api_event_free() when no longer needed.
 788  *
 789  * Returns: The new #FbApiEvent.
 790  */
 791 FbApiEvent *
 792 fb_api_event_dup(const FbApiEvent *event, gboolean deep);
 793
 794 /**
 795  * fb_api_event_reset:
 796  * @event: The #FbApiEvent.
 797  * @deep: #TRUE to free allocated data, otherwise #FALSE.
 798  *
 799  * Resets an #FbApiEvent.
 800  */
 801 void
 802 fb_api_event_reset(FbApiEvent *event, gboolean deep);
 803
 804 /**
 805  * fb_api_event_free:
 806  * @event: The #FbApiEvent.
 807  *
 808  * Frees all memory used by the #FbApiEvent.
 809  */
 810 void
 811 fb_api_event_free(FbApiEvent *event);
 812
 813 /**
 814  * fb_api_message_dup:
 815  * @msg: The #FbApiMessage or #NULL.
 816  * @deep: #TRUE to duplicate allocated data, otherwise #FALSE.
 817  *
 818  * Duplicates an #FbApiMessage. If @msg is #NULL, a new zero filled
 819  * #FbApiMessage is returned. The returned #FbApiMessage should be
 820  * freed with #fb_api_message_free() when no longer needed.
 821  *
 822  * Returns: The new #FbApiMessage.
 823  */
 824 FbApiMessage *
 825 fb_api_message_dup(const FbApiMessage *msg, gboolean deep);
 826
 827 /**
 828  * fb_api_message_reset:
 829  * @msg: The #FbApiMessage.
 830  * @deep: #TRUE to free allocated data, otherwise #FALSE.
 831  *
 832  * Resets an #FbApiMessage.
 833  */
 834 void
 835 fb_api_message_reset(FbApiMessage *msg, gboolean deep);
 836
 837 /**
 838  * fb_api_message_free:
 839  * @msg: The #FbApiMessage.
 840  *
 841  * Frees all memory used by the #FbApiMessage.
 842  */
 843 void
 844 fb_api_message_free(FbApiMessage *msg);
 845
 846 /**
 847  * fb_api_presence_dup:
 848  * @pres: The #FbApiPresence or #NULL.
 849  *
 850  * Duplicates an #FbApiPresence. If @pres is #NULL, a new zero filled
 851  * #FbApiPresence is returned. The returned #FbApiPresence should be
 852  * freed with #fb_api_presence_free() when no longer needed.
 853  *
 854  * Returns: The new #FbApiPresence.
 855  */
 856 FbApiPresence *
 857 fb_api_presence_dup(const FbApiPresence *pres);
 858
 859 /**
 860  * fb_api_presence_reset:
 861  * @pres: The #FbApiPresence.
 862  *
 863  * Resets an #FbApiPresence.
 864  */
 865 void
 866 fb_api_presence_reset(FbApiPresence *pres);
 867
 868 /**
 869  * fb_api_presence_free:
 870  * @pres: The #FbApiPresence.
 871  *
 872  * Frees all memory used by the #FbApiPresence.
 873  */
 874 void
 875 fb_api_presence_free(FbApiPresence *pres);
 876
 877 /**
 878  * fb_api_thread_dup:
 879  * @thrd: The #FbApiThread or #NULL.
 880  * @deep: #TRUE to duplicate allocated data, otherwise #FALSE.
 881  *
 882  * Duplicates an #FbApiThread. If @thrd is #NULL, a new zero filled
 883  * #FbApiThread is returned. The returned #FbApiThread should be freed
 884  * with #fb_api_thread_free() when no longer needed.
 885  *
 886  * Returns: The new #FbApiThread.
 887  */
 888 FbApiThread *
 889 fb_api_thread_dup(const FbApiThread *thrd, gboolean deep);
 890
 891 /**
 892  * fb_api_thread_reset:
 893  * @thrd: The #FbApiThread.
 894  * @deep: #TRUE to free allocated data, otherwise #FALSE.
 895  *
 896  * Resets an #FbApiThread.
 897  */
 898 void
 899 fb_api_thread_reset(FbApiThread *thrd, gboolean deep);
 900
 901 /**
 902  * fb_api_thread_free:
 903  * @thrd: The #FbApiThread.
 904  *
 905  * Frees all memory used by the #FbApiThread.
 906  */
 907 void
 908 fb_api_thread_free(FbApiThread *thrd);
 909
 910 /**
 911  * fb_api_typing_dup:
 912  * @typg: The #FbApiTyping or #NULL.
 913  *
 914  * Duplicates an #FbApiTyping. If @typg is #NULL, a new zero filled
 915  * #FbApiTyping is returned. The returned #FbApiTyping should be freed
 916  * with #fb_api_typing_free() when no longer needed.
 917  *
 918  * Returns: The new #FbApiTyping.
 919  */
 920 FbApiTyping *
 921 fb_api_typing_dup(const FbApiTyping *typg);
 922
 923 /**
 924  * fb_api_typing_reset:
 925  * @typg: The #FbApiTyping.
 926  *
 927  * Resets an #FbApiTyping.
 928  */
 929 void
 930 fb_api_typing_reset(FbApiTyping *typg);
 931
 932 /**
 933  * fb_api_typing_free:
 934  * @typg: The #FbApiTyping.
 935  *
 936  * Frees all memory used by the #FbApiTyping.
 937  */
 938 void
 939 fb_api_typing_free(FbApiTyping *typg);
 940
 941 /**
 942  * fb_api_user_dup:
 943  * @user: The #FbApiUser or #NULL.
 944  * @deep: #TRUE to duplicate allocated data, otherwise #FALSE.
 945  *
 946  * Duplicates an #FbApiUser. If @user is #NULL, a new zero filled
 947  * #FbApiUser is returned. The returned #FbApiUser should be freed with
 948  * #fb_api_user_free() when no longer needed.
 949  *
 950  * Returns: The new #FbApiUser.
 951  */
 952 FbApiUser *
 953 fb_api_user_dup(const FbApiUser *user, gboolean deep);
 954
 955 /**
 956  * fb_api_user_reset:
 957  * @user: The #FbApiUser.
 958  * @deep: #TRUE to free allocated data, otherwise #FALSE.
 959  *
 960  * Resets an #FbApiUser.
 961  */
 962 void
 963 fb_api_user_reset(FbApiUser *user, gboolean deep);
 964
 965 /**
 966  * fb_api_user_free:
 967  * @user: The #FbApiUser.
 968  *
 969  * Frees all memory used by the #FbApiUser.
 970  */
 971 void
 972 fb_api_user_free(FbApiUser *user);
 973
 974 #endif /* PURPLE_FACEBOOK_API_H */