1 /* 2 * Copyright 2014-2016 James Geboski <jgeboski@gmail.com> 3 * 4 * This program is free software: you can redistribute it and/or modify 5 * it under the terms of the GNU General Public License as published by 6 * the Free Software Foundation, either version 2 of the License, or 7 * (at your option) any later version. 8 * 9 * This program is distributed in the hope that it will be useful, 10 * but WITHOUT ANY WARRANTY; without even the implied warranty of 11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 12 * GNU General Public License for more details. 13 * 14 * You should have received a copy of the GNU General Public License 15 * along with this program. If not, see <http://www.gnu.org/licenses/>. 16 */ 17 18 #ifndef _FACEBOOK_HTTP_H_ 19 #define _FACEBOOK_HTTP_H_ 20 21 /** 22 * SECTION:http 23 * @section_id: facebook-http 24 * @short_description: <filename>facebook-http.h</filename> 25 * @title: HTTP Client 26 * 27 * The HTTP client. 28 */ 29 30 #include <http_client.h> 31 32 #include "facebook-glib.h" 33 34 #define FB_TYPE_HTTP (fb_http_get_type()) 35 #define FB_HTTP(obj) (G_TYPE_CHECK_INSTANCE_CAST((obj), FB_TYPE_HTTP, FbHttp)) 36 #define FB_HTTP_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST((klass), FB_TYPE_HTTP, FbHttpClass)) 37 #define FB_IS_HTTP(obj) (G_TYPE_CHECK_INSTANCE_TYPE((obj), FB_TYPE_HTTP)) 38 #define FB_IS_HTTP_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE((klass), FB_TYPE_HTTP)) 39 #define FB_HTTP_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS((obj), FB_TYPE_HTTP, FbHttpClass)) 40 41 #define FB_TYPE_HTTP_REQUEST (fb_http_request_get_type()) 42 #define FB_HTTP_REQUEST(obj) (G_TYPE_CHECK_INSTANCE_CAST((obj), FB_TYPE_HTTP_REQUEST, FbHttpRequest)) 43 #define FB_HTTP_REQUEST_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST((klass), FB_TYPE_HTTP_REQUEST, FbHttpRequestClass)) 44 #define FB_IS_HTTP_REQUEST(obj) (G_TYPE_CHECK_INSTANCE_TYPE((obj), FB_TYPE_HTTP_REQUEST)) 45 #define FB_IS_HTTP_REQUEST_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE((klass), FB_TYPE_HTTP_REQUEST)) 46 #define FB_HTTP_REQUEST_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS((obj), FB_TYPE_HTTP_REQUEST, FbHttpRequestClass)) 47 48 /** 49 * FB_HTTP_ERROR: 50 * 51 * The #GQuark of the domain of HTTP errors. 52 */ 53 #define FB_HTTP_ERROR fb_http_error_quark() 54 55 typedef struct _FbHttp FbHttp; 56 typedef struct _FbHttpClass FbHttpClass; 57 typedef struct _FbHttpPrivate FbHttpPrivate; 58 typedef struct _FbHttpRequest FbHttpRequest; 59 typedef struct _FbHttpRequestClass FbHttpRequestClass; 60 typedef struct _FbHttpRequestPrivate FbHttpRequestPrivate; 61 62 /** 63 * FbHttpValues: 64 * 65 * Represents a set of key/value HTTP values. 66 */ 67 typedef GHashTable FbHttpValues; 68 69 /** 70 * FbHttpFunc: 71 * @req: The #FbHttpRequest. 72 * @data: The user-defined data. 73 * 74 * The callback for HTTP requests. 75 */ 76 typedef void (*FbHttpFunc) (FbHttpRequest *req, gpointer data); 77 78 /** 79 * FbHttpError: 80 * @FB_HTTP_ERROR_SUCCESS: There is no error. 81 * @FB_HTTP_ERROR_INIT: The request failed to initialize. 82 * @FB_HTTP_ERROR_NOMATCH: The name does not match anything. 83 * 84 * The error codes for the #FB_HTTP_ERROR domain. 85 */ 86 typedef enum 87 { 88 FB_HTTP_ERROR_SUCCESS = 0, 89 FB_HTTP_ERROR_INIT, 90 FB_HTTP_ERROR_NOMATCH 91 } FbHttpError; 92 93 /** 94 * FbHttp: 95 * 96 * Represents an HTTP client. 97 */ 98 struct _FbHttp 99 { 100 /*< private >*/ 101 GObject parent; 102 FbHttpPrivate *priv; 103 }; 104 105 /** 106 * FbHttpClass: 107 * 108 * The base class for all #FbHttp's. 109 */ 110 struct _FbHttpClass 111 { 112 /*< private >*/ 113 GObjectClass parent_class; 114 }; 115 116 /** 117 * FbHttpRequest: 118 * 119 * Represents an HTTP request. 120 */ 121 struct _FbHttpRequest 122 { 123 /*< private >*/ 124 GObject parent; 125 FbHttpRequestPrivate *priv; 126 }; 127 128 /** 129 * FbHttpRequestClass: 130 * 131 * The base class for all #FbHttpRequest's. 132 */ 133 struct _FbHttpRequestClass 134 { 135 /*< private >*/ 136 GObjectClass parent_class; 137 }; 138 139 /** 140 * fb_http_get_type: 141 * 142 * Returns: The #GType for an #FbHttp. 143 */ 144 GType 145 fb_http_get_type(void); 146 147 /** 148 * fb_http_request_get_type: 149 * 150 * Returns: The #GType for an #FbHttpRequest. 151 */ 152 GType 153 fb_http_request_get_type(void); 154 155 /** 156 * fb_http_error_quark: 157 * 158 * Gets the #GQuark of the domain of HTTP errors. 159 * 160 * Returns: The #GQuark of the domain. 161 */ 162 GQuark 163 fb_http_error_quark(void); 164 165 /** 166 * fb_http_new: 167 * @agent: The User-Agent. 168 * 169 * Creates a new #FbHttp. The returned #FbHttp should be freed with 170 * #g_object_unref() when no longer needed. 171 * 172 * Returns: The new #FbHttp. 173 */ 174 FbHttp * 175 fb_http_new(const gchar *agent); 176 177 /** 178 * fb_http_get_cookies: 179 * @http: The #FbHttp. 180 * 181 * Gets the #FbHttpValues for cookies from the #FbHttp. The returned 182 * #FbHttpValues should not be freed. 183 * 184 * Returns: The #FbHttpValues. 185 */ 186 FbHttpValues * 187 fb_http_get_cookies(FbHttp *http); 188 189 /** 190 * fb_http_close_requests: 191 * @http: The #FbHttp. 192 * 193 * Closes all active #FbHttpRequest from the #FbHttp. 194 */ 195 void 196 fb_http_close_requests(FbHttp *http); 197 198 /** 199 * fb_http_cookies_parse_request: 200 * @http: The #FbHttp. 201 * @data: The string to parse. 202 * 203 * Parses and loads cookies from the #FbHttpRequest into the #FbHttp. 204 */ 205 void 206 fb_http_cookies_parse_request(FbHttp *http, FbHttpRequest *req); 207 208 /** 209 * fb_http_set_agent: 210 * @http: The #FbHttp. 211 * @agent: The new user agent string. 212 */ 213 void 214 fb_http_set_agent(FbHttp *http, const gchar *agent); 215 216 /** 217 * fb_http_request_new: 218 * @http: The #FbHttp. 219 * @url: The url. 220 * @post: #TRUE for the POST, otherwise #FALSE for GET. 221 * @func: The #FbHttpFunc. 222 * @data: The user-defined data. 223 * 224 * Creates a new #FbHttpRequest. The returned #FbHttpRequest should be 225 * freed with #g_object_unref() when no longer needed. 226 * 227 * Returns: The new #FbHttpRequest. 228 */ 229 FbHttpRequest * 230 fb_http_request_new(FbHttp *http, const gchar *url, gboolean post, 231 FbHttpFunc func, gpointer data); 232 233 /** 234 * fb_http_request_get_data: 235 * @req: The #FbHttpRequest. 236 * @code: The return location for size or #NULL. 237 * 238 * Gets the request data from the #FbHttpRequest. This should only be 239 * inside #FbHttpFunc passed to #fb_http_request_new(). 240 * 241 * Returns: The request data string. 242 */ 243 const gchar * 244 fb_http_request_get_data(FbHttpRequest *req, gsize *size); 245 246 /** 247 * fb_http_request_get_headers: 248 * @req: The #FbHttpRequest. 249 * 250 * Gets the #FbHttpValues for headers from the #FbHttpRequest. The 251 * returned #FbHttpValues should not be freed. 252 * 253 * Returns: The #FbHttpValues. 254 */ 255 FbHttpValues * 256 fb_http_request_get_headers(FbHttpRequest *req); 257 258 /** 259 * fb_http_request_get_params: 260 * @req: The #FbHttpRequest. 261 * 262 * Gets the #FbHttpValues for parameters from the #FbHttpRequest. The 263 * returned #FbHttpValues should not be freed. 264 * 265 * Returns: The #FbHttpValues. 266 */ 267 FbHttpValues * 268 fb_http_request_get_params(FbHttpRequest *req); 269 270 /** 271 * fb_http_request_get_status: 272 * @req: The #FbHttpRequest. 273 * @code: The return location for the status code or #NULL. 274 * 275 * Gets the request status from the #FbHttpRequest. This should only be 276 * inside #FbHttpFunc passed to #fb_http_request_new(). 277 * 278 * Returns: The status string. 279 */ 280 const gchar * 281 fb_http_request_get_status(FbHttpRequest *req, gint *code); 282 283 /** 284 * fb_http_request_take_error: 285 * @req: The #FbHttpRequest. 286 * 287 * Gets the #GError from the #FbHttpRequest. This should only be 288 * inside #FbHttpFunc passed to #fb_http_request_new(). The returned 289 * #GError should be freed with #g_error_free() when no longer needed. 290 * 291 * Returns: The #GError or #NULL. 292 */ 293 GError * 294 fb_http_request_take_error(FbHttpRequest *req); 295 296 /** 297 * fb_http_request_send: 298 * @req: The #FbHttpRequest. 299 * 300 * Sends the #FbHttpRequest to the remote server. 301 */ 302 void 303 fb_http_request_send(FbHttpRequest *req); 304 305 /** 306 * fb_http_urlcmp: 307 * @url1: The first URL. 308 * @url2: The second URL. 309 * @protocol: #TRUE to match the protocols, otherwise #FALSE. 310 * 311 * Compares two URLs. This is more reliable than just comparing two URL 312 * strings, as it avoids casing in some areas, while not in others. It 313 * can also, optionally, ignore the matching of the URL protocol. 314 * 315 * Returns: #TRUE if the URLs match, otherwise #FALSE. 316 */ 317 gboolean 318 fb_http_urlcmp(const gchar *url1, const gchar *url2, gboolean protocol); 319 320 /** 321 * fb_http_values_new: 322 * 323 * Creates a new #FbHttpValues. The returned #FbHttpValues should be 324 * freed with #fb_http_values_free() when no longer needed. 325 * 326 * Returns: The new #FbHttpValues. 327 */ 328 FbHttpValues * 329 fb_http_values_new(void); 330 331 /** 332 * fb_http_values_free: 333 * @values: The #FbHttpValues. 334 * 335 * Frees all memory used by the #FbHttpValues. 336 */ 337 void 338 fb_http_values_free(FbHttpValues *values); 339 340 /** 341 * fb_http_values_consume: 342 * @values: The #FbHttpValues. 343 * @consume: The #FbHttpValues to consume. 344 * 345 * Consumes another #FbHttpValues into the #FbHttpValues. This will 346 * overwrite any existing values. This will free the consumed 347 * #FbHttpValues. 348 */ 349 void 350 fb_http_values_consume(FbHttpValues *values, FbHttpValues *consume); 351 352 /** 353 * fb_http_values_parse: 354 * @values: The #FbHttpValues. 355 * @data: The data string. 356 * @isurl: #TRUE if @data is a URL, otherwise #FALSE. 357 * 358 * Parses and loads a parameter string into the #FbHttpValues. 359 */ 360 void 361 fb_http_values_parse(FbHttpValues *values, const gchar *data, gboolean isurl); 362 363 /** 364 * fb_http_values_str_cookies: 365 * @values: The #FbHttpValues. 366 * 367 * Creates a cookie string for the Set-Cookie header. The returned 368 * string should be freed with #g_free() when no longer needed. 369 * 370 * Returns: The cookie string. 371 */ 372 gchar * 373 fb_http_values_str_cookies(FbHttpValues *values); 374 375 /** 376 * fb_http_values_str_headers: 377 * @values: The #FbHttpValues. 378 * 379 * Creates a header string for a raw HTTP request. The returned string 380 * should be freed with #g_free() when no longer needed. 381 * 382 * Returns: The header string. 383 */ 384 gchar * 385 fb_http_values_str_headers(FbHttpValues *values); 386 387 /** 388 * fb_http_values_str_params: 389 * @values: The #FbHttpValues. 390 * @url: The URL or #NULL. 391 * 392 * Creates a parameter string for a raw HTTP request. If @url is 393 * non-#NULL, then the parameters are appended to @url. The returned 394 * string should be freed with #g_free() when no longer needed. 395 * 396 * Returns: The parameter string. 397 */ 398 gchar * 399 fb_http_values_str_params(FbHttpValues *values, const gchar *url); 400 401 /** 402 * fb_http_values_remove: 403 * @values: The #FbHttpValues. 404 * @name: The value name. 405 * 406 * Removes a value from the #FbHttpValues. 407 * 408 * Returns: #TRUE if the value was removed, otherwise #FALSE. 409 */ 410 gboolean 411 fb_http_values_remove(FbHttpValues *values, const gchar *name); 412 413 /** 414 * fb_http_values_get_keys: 415 * @values: The #FbHttpValues. 416 * 417 * Gets a #GList of keys from the #FbHttpValues. 418 * 419 * Returns: The #GList of keys. 420 */ 421 GList * 422 fb_http_values_get_keys(FbHttpValues *values); 423 424 /** 425 * fb_http_values_get_bool: 426 * @values: The #FbHttpValues. 427 * @name: The value name. 428 * @error: The return location for the #GError or #NULL. 429 * 430 * Gets a boolean value from the #FbHttpValues. This optionally assigns 431 * an appropriate #GError upon failure. 432 * 433 * Return: The boolean value. 434 */ 435 gboolean 436 fb_http_values_get_bool(FbHttpValues *values, const gchar *name, 437 GError **error); 438 439 /** 440 * fb_http_values_get_dbl: 441 * @values: The #FbHttpValues. 442 * @name: The value name. 443 * @error: The return location for the #GError or #NULL. 444 * 445 * Gets a floating point value from the #FbHttpValues. This optionally 446 * assigns an appropriate #GError upon failure. 447 * 448 * Return: The floating point value. 449 */ 450 gdouble 451 fb_http_values_get_dbl(FbHttpValues *values, const gchar *name, 452 GError **error); 453 454 /** 455 * fb_http_values_get_int: 456 * @values: The #FbHttpValues. 457 * @name: The value name. 458 * @error: The return location for the #GError or #NULL. 459 * 460 * Gets an integer value from the #FbHttpValues. This optionally 461 * assigns an appropriate #GError upon failure. 462 * 463 * Return: The integer value. 464 */ 465 gint64 466 fb_http_values_get_int(FbHttpValues *values, const gchar *name, 467 GError **error); 468 469 /** 470 * fb_http_values_get_str: 471 * @values: The #FbHttpValues. 472 * @name: The value name. 473 * @error: The return location for the #GError or #NULL. 474 * 475 * Gets a string value from the #FbHttpValues. This optionally assigns 476 * an appropriate #GError upon failure. 477 * 478 * Return: The string value. 479 */ 480 const gchar * 481 fb_http_values_get_str(FbHttpValues *values, const gchar *name, 482 GError **error); 483 484 /** 485 * fb_http_values_dup_str: 486 * @values: The #FbHttpValues. 487 * @name: The value name. 488 * @error: The return location for the #GError or #NULL. 489 * 490 * Gets a duplicated string value from the #FbHttpValues. This 491 * optionally assigns an appropriate #GError upon failure. The returned 492 * string should be freed with #g_free() when no longer needed. 493 * 494 * Return: The duplicated string value. 495 */ 496 gchar * 497 fb_http_values_dup_str(FbHttpValues *values, const gchar *name, 498 GError **error); 499 500 /** 501 * fb_http_values_set_bool: 502 * @values: The #FbHttpValues. 503 * @name: The value name. 504 * @value: The value. 505 * 506 * Sets a boolean value to the #FbHttpValues. 507 */ 508 void 509 fb_http_values_set_bool(FbHttpValues *values, const gchar *name, 510 gboolean value); 511 512 /** 513 * fb_http_values_set_dbl: 514 * @values: The #FbHttpValues. 515 * @name: The value name. 516 * @value: The value. 517 * 518 * Sets a floating point value to the #FbHttpValues. 519 */ 520 void 521 fb_http_values_set_dbl(FbHttpValues *values, const gchar *name, gdouble value); 522 523 /** 524 * fb_http_values_set_int: 525 * @values: The #FbHttpValues. 526 * @name: The value name. 527 * @value: The value. 528 * 529 * Sets an integer value to the #FbHttpValues. 530 */ 531 void 532 fb_http_values_set_int(FbHttpValues *values, const gchar *name, gint64 value); 533 534 /** 535 * fb_http_values_set_str: 536 * @values: The #FbHttpValues. 537 * @name: The value name. 538 * @value: The value. 539 * 540 * Sets a string value to the #FbHttpValues. 541 */ 542 void 543 fb_http_values_set_str(FbHttpValues *values, const gchar *name, 544 const gchar *value); 545 546 /** 547 * fb_http_values_set_strf: 548 * @values: The #FbHttpValues. 549 * @name: The value name. 550 * @format: The format string literal. 551 * @...: The arguments for @format. 552 * 553 * Sets a formatted string value to the #FbHttpValues. 554 */ 555 void 556 fb_http_values_set_strf(FbHttpValues *values, const gchar *name, 557 const gchar *format, ...) 558 G_GNUC_PRINTF(3, 4); 559 560 #endif /* _FACEBOOK_HTTP_H_ */ 561