libpurple/protocols/facebook/thrift.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_THRIFT_H
  23 #define PURPLE_FACEBOOK_THRIFT_H
  24
  25 /**
  26  * SECTION:thrift
  27  * @section_id: facebook-thrift
  28  * @short_description: <filename>thrift.h</filename>
  29  * @title: Thrift Reader/Writer
  30  *
  31  * The Thrift reader/writer.
  32  */
  33
  34 #include <glib.h>
  35 #include <glib-object.h>
  36
  37 #define FB_TYPE_THRIFT  fb_thrift_get_type()
  38
  39 /**
  40  * FbThriftType:
  41  * @FB_THRIFT_TYPE_STOP: A stopper for certain types.
  42  * @FB_THRIFT_TYPE_VOID: A void or empty value.
  43  * @FB_THRIFT_TYPE_BOOL: A boolean (#TRUE or #FALSE).
  44  * @FB_THRIFT_TYPE_BYTE: A signed 8-bit integer.
  45  * @FB_THRIFT_TYPE_DOUBLE: A 64-bit floating point number.
  46  * @FB_THRIFT_TYPE_I16: A signed 16-bit integer.
  47  * @FB_THRIFT_TYPE_I32: A signed 32-bit integer.
  48  * @FB_THRIFT_TYPE_I64: A signed 64-bit integer.
  49  * @FB_THRIFT_TYPE_STRING: A UTF-8 encoded string.
  50  * @FB_THRIFT_TYPE_STRUCT: A set of typed fields.
  51  * @FB_THRIFT_TYPE_MAP: A map of unique keys to values.
  52  * @FB_THRIFT_TYPE_SET: A unique set of values.
  53  * @FB_THRIFT_TYPE_LIST: A ordered list of values.
  54  * @FB_THRIFT_TYPE_ENUM: A 32-bit enumerated list.
  55  * @FB_THRIFT_TYPE_UNKNOWN: An unknown type.
  56  *
  57  * The Thrift data types.
  58  */
  59 typedef enum
  60 {
  61         FB_THRIFT_TYPE_STOP = 0,
  62         FB_THRIFT_TYPE_VOID = 1,
  63         FB_THRIFT_TYPE_BOOL = 2,
  64         FB_THRIFT_TYPE_BYTE = 3,
  65         FB_THRIFT_TYPE_DOUBLE = 4,
  66         FB_THRIFT_TYPE_I16 = 6,
  67         FB_THRIFT_TYPE_I32 = 8,
  68         FB_THRIFT_TYPE_I64 = 10,
  69         FB_THRIFT_TYPE_STRING = 11,
  70         FB_THRIFT_TYPE_STRUCT = 12,
  71         FB_THRIFT_TYPE_MAP = 13,
  72         FB_THRIFT_TYPE_SET = 14,
  73         FB_THRIFT_TYPE_LIST = 15,
  74         FB_THRIFT_TYPE_ENUM = 16,
  75
  76         FB_THRIFT_TYPE_UNKNOWN
  77 } FbThriftType;
  78
  79 /**
  80  * fb_thrift_get_type:
  81  *
  82  * Returns: The #GType for an #FbThrift.
  83  */
  84 G_DECLARE_FINAL_TYPE(FbThrift, fb_thrift, FB, THRIFT, GObject)
  85
  86 /**
  87  * fb_thrift_new:
  88  * @bytes: The #GByteArray to read or write.
  89  * @offset: The offset in bytes of the data in @bytes.
  90  *
  91  * Creates a new #FbThrift. The returned #FbThrift should be freed with
  92  * #g_object_unref() when no longer needed. This will optionally use a
  93  * #GByteArray at an offset, rather than a newly created and internal
  94  * #GByteArray.
  95  *
  96  * Returns: The new #FbThrift.
  97  */
  98 FbThrift *
  99 fb_thrift_new(GByteArray *bytes, guint offset);
 100
 101 /**
 102  * fb_thrift_get_bytes:
 103  * @thft: The #FbThrift.
 104  *
 105  * Gets the underlying #GByteArray of an #FbThrift.
 106  *
 107  * Returns: The #GByteArray.
 108  */
 109 const GByteArray *
 110 fb_thrift_get_bytes(FbThrift *thft);
 111
 112 /**
 113  * fb_thrift_get_pos:
 114  * @thft: The #FbThrift.
 115  *
 116  * Gets the cursor position of an #FbThrift.
 117  *
 118  * Returns: The cursor position.
 119  */
 120 guint
 121 fb_thrift_get_pos(FbThrift *thft);
 122
 123 /**
 124  * fb_thrift_set_pos:
 125  * @thft: The #FbThrift.
 126  * @pos: The position.
 127  *
 128  * Sets the cursor position of an #FbThrift.
 129  *
 130  * Returns: The #GByteArray.
 131  */
 132 void
 133 fb_thrift_set_pos(FbThrift *thft, guint pos);
 134
 135 /**
 136  * fb_thrift_reset:
 137  * @thft: The #FbThrift.
 138  *
 139  * Resets the cursor position of an #FbThrift.
 140  *
 141  * Returns: The #GByteArray.
 142  */
 143 void
 144 fb_thrift_reset(FbThrift *thft);
 145
 146 /**
 147  * fb_thrift_read:
 148  * @thft: The #FbThrift.
 149  * @data: The data buffer.
 150  * @size: The size of @buffer.
 151  *
 152  * Reads data from the #FbThrift into a buffer. If @data is #NULL, this
 153  * will simply advance the cursor position.
 154  *
 155  * Returns: #TRUE if the data was read, otherwise #FALSE.
 156  */
 157 gboolean
 158 fb_thrift_read(FbThrift *thft, gpointer data, guint size);
 159
 160 /**
 161  * fb_thrift_read_bool:
 162  * @thft: The #FbThrift.
 163  * @value: The return location for the value or #NULL.
 164  *
 165  * Reads a boolean value from the #FbThrift. If @value is #NULL, this
 166  * will simply advance the cursor position.
 167  *
 168  * Returns: #TRUE if the value was read, otherwise #FALSE.
 169  */
 170 gboolean
 171 fb_thrift_read_bool(FbThrift *thft, gboolean *value);
 172
 173 /**
 174  * fb_thrift_read_byte:
 175  * @thft: The #FbThrift.
 176  * @value: The return location for the value or #NULL.
 177  *
 178  * Reads an 8-bit integer value from the #FbThrift. If @value is #NULL,
 179  * this will simply advance the cursor position.
 180  *
 181  * Returns: #TRUE if the value was read, otherwise #FALSE.
 182  */
 183 gboolean
 184 fb_thrift_read_byte(FbThrift *thft, guint8 *value);
 185
 186 /**
 187  * fb_thrift_read_dbl:
 188  * @thft: The #FbThrift.
 189  * @value: The return location for the value or #NULL.
 190  *
 191  * Reads a 64-bit floating point value from the #FbThrift. If @value
 192  * is #NULL, this will simply advance the cursor position.
 193  *
 194  * Returns: #TRUE if the value was read, otherwise #FALSE.
 195  */
 196 gboolean
 197 fb_thrift_read_dbl(FbThrift *thft, gdouble *value);
 198
 199 /**
 200  * fb_thrift_read_i16:
 201  * @thft: The #FbThrift.
 202  * @value: The return location for the value or #NULL.
 203  *
 204  * Reads a signed 16-bit integer value from the #FbThrift. This will
 205  * convert the integer from the zig-zag format. If @value is #NULL,
 206  * this will simply advance the cursor position.
 207  *
 208  * Returns: #TRUE if the value was read, otherwise #FALSE.
 209  */
 210 gboolean
 211 fb_thrift_read_i16(FbThrift *thft, gint16 *value);
 212
 213 /**
 214  * fb_thrift_read_vi16:
 215  * @thft: The #FbThrift.
 216  * @value: The return location for the value or #NULL.
 217  *
 218  * Reads a 16-bit integer value from the #FbThrift. This reads the raw
 219  * integer value without converting it from the zig-zag format. If
 220  * @value is #NULL, this will simply advance the cursor position.
 221  *
 222  * Returns: #TRUE if the value was read, otherwise #FALSE.
 223  */
 224 gboolean
 225 fb_thrift_read_vi16(FbThrift *thft, guint16 *value);
 226
 227 /**
 228  * fb_thrift_read_i32:
 229  * @thft: The #FbThrift.
 230  * @value: The return location for the value or #NULL.
 231  *
 232  * Reads a signed 32-bit integer value from the #FbThrift. This will
 233  * convert the integer from the zig-zag format. If @value is #NULL,
 234  * this will simply advance the cursor position.
 235  *
 236  * Returns: #TRUE if the value was read, otherwise #FALSE.
 237  */
 238 gboolean
 239 fb_thrift_read_i32(FbThrift *thft, gint32 *value);
 240
 241 /**
 242  * fb_thrift_read_vi32:
 243  * @thft: The #FbThrift.
 244  * @value: The return location for the value or #NULL.
 245  *
 246  * Reads a 32-bit integer value from the #FbThrift. This reads the raw
 247  * integer value without converting it from the zig-zag format. If
 248  * @value is #NULL, this will simply advance the cursor position.
 249  *
 250  * Returns: #TRUE if the value was read, otherwise #FALSE.
 251  */
 252 gboolean
 253 fb_thrift_read_vi32(FbThrift *thft, guint32 *value);
 254
 255 /**
 256  * fb_thrift_read_i64:
 257  * @thft: The #FbThrift.
 258  * @value: The return location for the value or #NULL.
 259  *
 260  * Reads a signed 64-bit integer value from the #FbThrift. This will
 261  * convert the integer from the zig-zag format. If @value is #NULL,
 262  * this will simply advance the cursor position.
 263  *
 264  * Returns: #TRUE if the value was read, otherwise #FALSE.
 265  */
 266 gboolean
 267 fb_thrift_read_i64(FbThrift *thft, gint64 *value);
 268
 269 /**
 270  * fb_thrift_read_vi64:
 271  * @thft: The #FbThrift.
 272  * @value: The return location for the value or #NULL.
 273  *
 274  * Reads a 64-bit integer value from the #FbThrift. This reads the raw
 275  * integer value without converting it from the zig-zag format. If
 276  * @value is #NULL, this will simply advance the cursor position.
 277  *
 278  * Returns: #TRUE if the value was read, otherwise #FALSE.
 279  */
 280 gboolean
 281 fb_thrift_read_vi64(FbThrift *thft, guint64 *value);
 282
 283 /**
 284  * fb_thrift_read_str:
 285  * @thft: The #FbThrift.
 286  * @value: The return location for the value or #NULL.
 287  *
 288  * Reads a string value from the #FbThrift. The value returned to
 289  * @value should be freed with #g_free() when no longer needed. If
 290  * @value is #NULL, this will simply advance the cursor position.
 291  *
 292  * Returns: #TRUE if the value was read, otherwise #FALSE.
 293  */
 294 gboolean
 295 fb_thrift_read_str(FbThrift *thft, gchar **value);
 296
 297 /**
 298  * fb_thrift_read_field:
 299  * @thft: The #FbThrift.
 300  * @type: The return location for the #FbThriftType.
 301  * @id: The return location for the identifier.
 302  * @lastid: The identifier of the previous field.
 303  *
 304  * Reads a field header from the #FbThrift.
 305  *
 306  * Returns: #TRUE if the field header was read, otherwise #FALSE.
 307  */
 308 gboolean
 309 fb_thrift_read_field(FbThrift *thft, FbThriftType *type, gint16 *id,
 310                                          gint16 lastid);
 311
 312 /**
 313  * fb_thrift_read_stop:
 314  * @thft: The #FbThrift.
 315  *
 316  * Reads a field stop from the #FbThrift.
 317  *
 318  * Returns: #TRUE if the field stop was read, otherwise #FALSE.
 319  */
 320 gboolean
 321 fb_thrift_read_stop(FbThrift *thft);
 322
 323 /**
 324  * fb_thrift_read_isstop:
 325  * @thft: The #FbThrift.
 326  *
 327  * Determines if the next byte of the #FbThrift is a field stop.
 328  *
 329  * Returns: #TRUE if the next byte is a field stop, otherwise #FALSE.
 330  */
 331 gboolean
 332 fb_thrift_read_isstop(FbThrift *thft);
 333
 334 /**
 335  * fb_thrift_read_list:
 336  * @thft: The #FbThrift.
 337  * @type: The return location for the #FbThriftType.
 338  * @size: The return location for the size.
 339  *
 340  * Reads a list header from the #FbThrift.
 341  *
 342  * Returns: #TRUE if the list header was read, otherwise #FALSE.
 343  */
 344 gboolean
 345 fb_thrift_read_list(FbThrift *thft, FbThriftType *type, guint *size);
 346
 347 /**
 348  * fb_thrift_read_map:
 349  * @thft: The #FbThrift.
 350  * @ktype: The return location for the key #FbThriftType.
 351  * @vtype: The return location for the value #FbThriftType.
 352  * @size: The return location for the size.
 353  *
 354  * Reads a map header from the #FbThrift.
 355  *
 356  * Returns: #TRUE if the map header was read, otherwise #FALSE.
 357  */
 358 gboolean
 359 fb_thrift_read_map(FbThrift *thft, FbThriftType *ktype, FbThriftType *vtype,
 360                    guint *size);
 361
 362 /**
 363  * fb_thrift_read_set:
 364  * @thft: The #FbThrift.
 365  * @type: The return location for the #FbThriftType.
 366  * @size: The return location for the size.
 367  *
 368  * Reads a set header from the #FbThrift.
 369  *
 370  * Returns: #TRUE if the set header was read, otherwise #FALSE.
 371  */
 372 gboolean
 373 fb_thrift_read_set(FbThrift *thft, FbThriftType *type, guint *size);
 374
 375 /**
 376  * fb_thrift_write:
 377  * @thft: The #FbThrift.
 378  * @data: The data buffer.
 379  * @size: The size of @buffer.
 380  *
 381  * Writes data to the #FbThrift.
 382  */
 383 void
 384 fb_thrift_write(FbThrift *thft, gconstpointer data, guint size);
 385
 386 /**
 387  * fb_thrift_write_bool:
 388  * @thft: The #FbThrift.
 389  * @value: The value.
 390  *
 391  * Writes a boolean value to the #FbThrift.
 392  */
 393 void
 394 fb_thrift_write_bool(FbThrift *thft, gboolean value);
 395
 396 /**
 397  * fb_thrift_write_byte:
 398  * @thft: The #FbThrift.
 399  * @value: The value.
 400  *
 401  * Writes an 8-bit integer value to the #FbThrift.
 402  */
 403 void
 404 fb_thrift_write_byte(FbThrift *thft, guint8 value);
 405
 406 /**
 407  * fb_thrift_write_dbl:
 408  * @thft: The #FbThrift.
 409  * @value: The value.
 410  *
 411  * Writes a 64-bit floating point value to the #FbThrift.
 412  */
 413 void
 414 fb_thrift_write_dbl(FbThrift *thft, gdouble value);
 415
 416 /**
 417  * fb_thrift_write_i16:
 418  * @thft: The #FbThrift.
 419  * @value: The value.
 420  *
 421  * Writes a signed 16-bit integer value to the #FbThrift. This will
 422  * convert the integer to the zig-zag format.
 423  */
 424 void
 425 fb_thrift_write_i16(FbThrift *thft, gint16 value);
 426
 427 /**
 428  * fb_thrift_write_vi16:
 429  * @thft: The #FbThrift.
 430  * @value: The value.
 431  *
 432  * Writes a 16-bit integer value to the #FbThrift. This writes the raw
 433  * integer value without converting it to the zig-zag format.
 434  */
 435 void
 436 fb_thrift_write_vi16(FbThrift *thft, guint16 value);
 437
 438 /**
 439  * fb_thrift_write_i32:
 440  * @thft: The #FbThrift.
 441  * @value: The value.
 442  *
 443  * Writes a signed 32-bit integer value to the #FbThrift. This will
 444  * convert the integer to the zig-zag format.
 445  */
 446 void
 447 fb_thrift_write_i32(FbThrift *thft, gint32 value);
 448
 449 /**
 450  * fb_thrift_write_vi32:
 451  * @thft: The #FbThrift.
 452  * @value: The value.
 453  *
 454  * Writes a 32-bit integer value to the #FbThrift. This writes the raw
 455  * integer value without converting it to the zig-zag format.
 456  */
 457 void
 458 fb_thrift_write_vi32(FbThrift *thft, guint32 value);
 459
 460 /**
 461  * fb_thrift_write_i64:
 462  * @thft: The #FbThrift.
 463  * @value: The value.
 464  *
 465  * Writes a signed 64-bit integer value to the #FbThrift. This will
 466  * convert the integer to the zig-zag format.
 467  */
 468 void
 469 fb_thrift_write_i64(FbThrift *thft, gint64 value);
 470
 471 /**
 472  * fb_thrift_write_vi64:
 473  * @thft: The #FbThrift.
 474  * @value: The value.
 475  *
 476  * Writes a 64-bit integer value to the #FbThrift. This writes the raw
 477  * integer value without converting it to the zig-zag format.
 478  */
 479 void
 480 fb_thrift_write_vi64(FbThrift *thft, guint64 value);
 481
 482 /**
 483  * fb_thrift_write_str:
 484  * @thft: The #FbThrift.
 485  * @value: The value.
 486  *
 487  * Writes a string value to the #FbThrift.
 488  */
 489 void
 490 fb_thrift_write_str(FbThrift *thft, const gchar *value);
 491
 492 /**
 493  * fb_thrift_write_field:
 494  * @thft: The #FbThrift.
 495  * @type: The #FbThriftType.
 496  * @id: The identifier.
 497  * @lastid: The identifier of the previous field.
 498  *
 499  * Writes a field header to the #FbThrift.
 500  */
 501 void
 502 fb_thrift_write_field(FbThrift *thft, FbThriftType type, gint16 id,
 503                                           gint16 lastid);
 504
 505 /**
 506  * fb_thrift_write_stop:
 507  * @thft: The #FbThrift.
 508  *
 509  * Writes a field stop to the #FbThrift.
 510  */
 511 void
 512 fb_thrift_write_stop(FbThrift *thft);
 513
 514 /**
 515  * fb_thrift_write_list:
 516  * @thft: The #FbThrift.
 517  * @type: The #FbThriftType.
 518  * @size: The size.
 519  *
 520  * Writes a list header to the #FbThrift.
 521  */
 522 void
 523 fb_thrift_write_list(FbThrift *thft, FbThriftType type, guint size);
 524
 525 /**
 526  * fb_thrift_write_map:
 527  * @thft: The #FbThrift.
 528  * @ktype: The key #FbThriftType.
 529  * @vtype: The value #FbThriftType.
 530  * @size: The size.
 531  *
 532  * Writes a map header to the #FbThrift.
 533  */
 534 void
 535 fb_thrift_write_map(FbThrift *thft, FbThriftType ktype, FbThriftType vtype,
 536                     guint size);
 537
 538 /**
 539  * fb_thrift_write_set:
 540  * @thft: The #FbThrift.
 541  * @type: The #FbThriftType.
 542  * @size: The size.
 543  *
 544  * Writes a set header to the #FbThrift.
 545  */
 546 void
 547 fb_thrift_write_set(FbThrift *thft, FbThriftType type, guint size);
 548
 549 /**
 550  * fb_thrift_t2ct:
 551  * @type: The #FbThriftType.
 552  *
 553  * Converts a #FbThriftType to a compact type.
 554  *
 555  * Return: The equivalent compact type.
 556  */
 557 guint8
 558 fb_thrift_t2ct(FbThriftType type);
 559
 560 /**
 561  * fb_thrift_ct2t:
 562  * @type: The compact type.
 563  *
 564  * Converts a compact type to an #FbThriftType.
 565  *
 566  * Return: The equivalent #FbThriftType.
 567  */
 568 FbThriftType
 569 fb_thrift_ct2t(guint8 type);
 570
 571 #endif /* PURPLE_FACEBOOK_THRIFT_H */