libpurple/protocols/facebook/http.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_HTTP_H
  23 #define PURPLE_FACEBOOK_HTTP_H
  24
  25 /**
  26  * SECTION:http
  27  * @section_id: facebook-http
  28  * @short_description: <filename>http.h</filename>
  29  * @title: HTTP Utilities
  30  *
  31  * The HTTP utilities.
  32  */
  33
  34 #include <glib.h>
  35
  36 #include <libpurple/http.h>
  37
  38 /**
  39  * FB_HTTP_ERROR:
  40  *
  41  * The #GQuark of the domain of HTTP errors.
  42  */
  43 #define FB_HTTP_ERROR  fb_http_error_quark()
  44
  45 /**
  46  * FbHttpConns:
  47  *
  48  * Represents a set of #PurpleHttpConnection.
  49  */
  50 typedef struct _FbHttpConns FbHttpConns;
  51
  52 /**
  53  * FbHttpParams:
  54  *
  55  * Represents a set of key/value HTTP parameters.
  56  */
  57 typedef GHashTable FbHttpParams;
  58
  59 /**
  60  * FbHttpError:
  61  * @FB_HTTP_ERROR_SUCCESS: There is no error.
  62  * @FB_HTTP_ERROR_NOMATCH: The name does not match anything.
  63  *
  64  * The error codes for the #FB_HTTP_ERROR domain.
  65  */
  66 typedef enum
  67 {
  68         FB_HTTP_ERROR_SUCCESS = 0,
  69         FB_HTTP_ERROR_NOMATCH
  70 } FbHttpError;
  71
  72 /**
  73  * fb_http_error_quark:
  74  *
  75  * Gets the #GQuark of the domain of HTTP errors.
  76  *
  77  * Returns: The #GQuark of the domain.
  78  */
  79 GQuark
  80 fb_http_error_quark(void);
  81
  82 /**
  83  * fb_http_conns_new:
  84  *
  85  * Creates a new #FbHttpConns. The returned #FbHttpConns should be
  86  * freed with #fb_http_conns_free() when no longer needed.
  87  *
  88  * Returns: The new #FbHttpConns.
  89  */
  90 FbHttpConns *
  91 fb_http_conns_new(void);
  92
  93 /**
  94  * fb_http_conns_free:
  95  * @cons: The #FbHttpConns.
  96  *
  97  * Frees all memory used by the #FbHttpConns. This will *not* cancel
  98  * the any of the added #PurpleHttpConnection.
  99  */
 100 void
 101 fb_http_conns_free(FbHttpConns *cons);
 102
 103 /**
 104  * fb_http_conns_cancel_all:
 105  * @cons: The #FbHttpConns.
 106  *
 107  * Cancels each #PurpleHttpConnection in the #FbHttpConns.
 108  */
 109 void
 110 fb_http_conns_cancel_all(FbHttpConns *cons);
 111
 112 /**
 113  * fb_http_conns_is_canceled:
 114  * @cons: The #FbHttpConns.
 115  *
 116  * Determines if the #FbHttpConns has been canceled.
 117  *
 118  * Returns: #TRUE if it has been canceled, otherwise #FALSE.
 119  */
 120 gboolean
 121 fb_http_conns_is_canceled(FbHttpConns *cons);
 122
 123 /**
 124  * fb_http_conns_add:
 125  * @cons: The #FbHttpConns.
 126  * @con: The #PurpleHttpConnection.
 127  *
 128  * Adds a #PurpleHttpConnection to the #FbHttpConns.
 129  */
 130 void
 131 fb_http_conns_add(FbHttpConns *cons, PurpleHttpConnection *con);
 132
 133 /**
 134  * fb_http_conns_remove:
 135  * @cons: The #FbHttpConns.
 136  * @con: The #PurpleHttpConnection.
 137  *
 138  * Removes a #PurpleHttpConnection from the #FbHttpConns.
 139  */
 140 void
 141 fb_http_conns_remove(FbHttpConns *cons, PurpleHttpConnection *con);
 142
 143 /**
 144  * fb_http_conns_reset:
 145  * @cons: The #FbHttpConns.
 146  *
 147  * Resets the #FbHttpConns. This removes each #PurpleHttpConnection
 148  * from the #FbHttpConns *without* canceling it. This allows the the
 149  * #FbHttpConns to be reused.
 150  */
 151 void
 152 fb_http_conns_reset(FbHttpConns *cons);
 153
 154 /**
 155  * fb_http_error_chk:
 156  * @res: The #PurpleHttpResponse.
 157  * @error: The return location for the #GError or #NULL.
 158  *
 159  * Checks a #PurpleHttpResponse for success. This optionally assigns an
 160  * appropriate #GError upon failure.
 161  *
 162  * Returns: #TRUE if the request was successful, otherwise #FALSE.
 163  */
 164 gboolean
 165 fb_http_error_chk(PurpleHttpResponse *res, GError **error);
 166
 167 /**
 168  * fb_http_params_new:
 169  *
 170  * Creates a new #FbHttpParams. The returned #FbHttpParams should be
 171  * freed with #fb_http_params_free() when no longer needed. Optionally,
 172  * instead of freeing, the returned #FbHttpParams can be closed with
 173  * #fb_http_params_close().
 174  *
 175  * Returns: The new #FbHttpParams.
 176  */
 177 FbHttpParams *
 178 fb_http_params_new(void);
 179
 180 /**
 181  * fb_http_params_new_parse:
 182  * @data: The string containing HTTP parameters.
 183  * @isurl: #TRUE if @data is a URL, otherwise #FALSE.
 184  *
 185  * Creates a new #FbHttpParams. This parses the #FbHttpParams from a
 186  * string, which can be a URL. The returned #FbHttpParams should be
 187  * freed with #fb_http_params_free() when no longer needed. Optionally,
 188  * instead of freeing, the returned #FbHttpParams can be closed with
 189  * #fb_http_params_close().
 190  *
 191  * Returns: The new #FbHttpParams.
 192  */
 193 FbHttpParams *
 194 fb_http_params_new_parse(const gchar *data, gboolean isurl);
 195
 196 /**
 197  * fb_http_params_free:
 198  * @params: The #FbHttpParams.
 199  *
 200  * Frees all memory used by the #FbHttpParams.
 201  */
 202 void
 203 fb_http_params_free(FbHttpParams *params);
 204
 205 /**
 206  * fb_http_params_close:
 207  * @params: The #FbHttpParams.
 208  * @url: The URL or #NULL.
 209  *
 210  * Closes the #FbHttpParams by returning a string representing the HTTP
 211  * parameters. If @url is non-#NULL, then the parameters are appended
 212  * to the value of @url. This frees the #FbHttpParams. The returned
 213  * string should be freed with #g_free() when no longer needed.
 214  *
 215  * Returns: The string representation of the HTTP parameters.
 216  */
 217 gchar *
 218 fb_http_params_close(FbHttpParams *params, const gchar *url);
 219
 220 /**
 221  * fb_http_params_get_bool:
 222  * @params: The #FbHttpParams.
 223  * @name: The parameter name.
 224  * @error: The return location for the #GError or #NULL.
 225  *
 226  * Gets a boolean value from the #FbHttpParams. This optionally assigns
 227  * an appropriate #GError upon failure.
 228  *
 229  * Return: The boolean value.
 230  */
 231 gboolean
 232 fb_http_params_get_bool(FbHttpParams *params, const gchar *name,
 233                         GError **error);
 234
 235 /**
 236  * fb_http_params_get_dbl:
 237  * @params: The #FbHttpParams.
 238  * @name: The parameter name.
 239  * @error: The return location for the #GError or #NULL.
 240  *
 241  * Gets a floating point value from the #FbHttpParams. This optionally
 242  * assigns an appropriate #GError upon failure.
 243  *
 244  * Return: The floating point value.
 245  */
 246 gdouble
 247 fb_http_params_get_dbl(FbHttpParams *params, const gchar *name,
 248                        GError **error);
 249
 250 /**
 251  * fb_http_params_get_int:
 252  * @params: The #FbHttpParams.
 253  * @name: The parameter name.
 254  * @error: The return location for the #GError or #NULL.
 255  *
 256  * Gets an integer value from the #FbHttpParams. This optionally
 257  * assigns an appropriate #GError upon failure.
 258  *
 259  * Return: The integer value.
 260  */
 261 gint64
 262 fb_http_params_get_int(FbHttpParams *params, const gchar *name,
 263                        GError **error);
 264
 265 /**
 266  * fb_http_params_get_str:
 267  * @params: The #FbHttpParams.
 268  * @name: The parameter name.
 269  * @error: The return location for the #GError or #NULL.
 270  *
 271  * Gets a string value from the #FbHttpParams. This optionally assigns
 272  * an appropriate #GError upon failure.
 273  *
 274  * Return: The string value.
 275  */
 276 const gchar *
 277 fb_http_params_get_str(FbHttpParams *params, const gchar *name,
 278                        GError **error);
 279
 280 /**
 281  * fb_http_params_dup_str:
 282  * @params: The #FbHttpParams.
 283  * @name: The parameter name.
 284  * @error: The return location for the #GError or #NULL.
 285  *
 286  * Gets a duplicated string value from the #FbHttpParams. This
 287  * optionally assigns an appropriate #GError upon failure. The returned
 288  * string should be freed with #g_free() when no longer needed.
 289  *
 290  * Return: The duplicated string value.
 291  */
 292 gchar *
 293 fb_http_params_dup_str(FbHttpParams *params, const gchar *name,
 294                        GError **error);
 295
 296 /**
 297  * fb_http_params_set_bool:
 298  * @params: The #FbHttpParams.
 299  * @name: The parameter name.
 300  * @value: The value.
 301  *
 302  * Sets a boolean value to the #FbHttpParams.
 303  */
 304 void
 305 fb_http_params_set_bool(FbHttpParams *params, const gchar *name,
 306                         gboolean value);
 307
 308 /**
 309  * fb_http_params_set_dbl:
 310  * @params: The #FbHttpParams.
 311  * @name: The parameter name.
 312  * @value: The value.
 313  *
 314  * Sets a floating point value to the #FbHttpParams.
 315  */
 316 void
 317 fb_http_params_set_dbl(FbHttpParams *params, const gchar *name, gdouble value);
 318
 319 /**
 320  * fb_http_params_set_int:
 321  * @params: The #FbHttpParams.
 322  * @name: The parameter name.
 323  * @value: The value.
 324  *
 325  * Sets an integer value to the #FbHttpParams.
 326  */
 327 void
 328 fb_http_params_set_int(FbHttpParams *params, const gchar *name, gint64 value);
 329
 330 /**
 331  * fb_http_params_set_str:
 332  * @params: The #FbHttpParams.
 333  * @name: The parameter name.
 334  * @value: The value.
 335  *
 336  * Sets a string value to the #FbHttpParams.
 337  */
 338 void
 339 fb_http_params_set_str(FbHttpParams *params, const gchar *name,
 340                        const gchar *value);
 341
 342 /**
 343  * fb_http_params_set_strf:
 344  * @params: The #FbHttpParams.
 345  * @name: The parameter name.
 346  * @format: The format string literal.
 347  * @...: The arguments for @format.
 348  *
 349  * Sets a formatted string value to the #FbHttpParams.
 350  */
 351 void
 352 fb_http_params_set_strf(FbHttpParams *params, const gchar *name,
 353                         const gchar *format, ...)
 354                         G_GNUC_PRINTF(3, 4);
 355
 356 /**
 357  * fb_http_urlcmp:
 358  * @url1: The first URL.
 359  * @url2: The second URL.
 360  * @protocol: #TRUE to match the protocols, otherwise #FALSE.
 361  *
 362  * Compares two URLs. This is more reliable than just comparing two URL
 363  * strings, as it avoids casing in some areas, while not in others. It
 364  * can also, optionally, ignore the matching of the URL protocol.
 365  *
 366  * Returns: #TRUE if the URLs match, otherwise #FALSE.
 367  */
 368 gboolean
 369 fb_http_urlcmp(const gchar *url1, const gchar *url2, gboolean protocol);
 370
 371 #endif /* PURPLE_FACEBOOK_HTTP_H */