lib/oauth.h

   1 /***************************************************************************\
   2 *                                                                           *
   3 *  BitlBee - An IRC to IM gateway                                           *
   4 *  Simple OAuth client (consumer) implementation.                           *
   5 *                                                                           *
   6 *  Copyright 2010 Wilmer van der Gaast <wilmer@gaast.net>                   *
   7 *                                                                           *
   8 *  This program is free software; you can redistribute it and/or modify     *
   9 *  it under the terms of the GNU General Public License as published by     *
  10 *  the Free Software Foundation; either version 2 of the License, or        *
  11 *  (at your option) any later version.                                      *
  12 *                                                                           *
  13 *  This program is distributed in the hope that it will be useful,          *
  14 *  but WITHOUT ANY WARRANTY; without even the implied warranty of           *
  15 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the            *
  16 *  GNU General Public License for more details.                             *
  17 *                                                                           *
  18 *  You should have received a copy of the GNU General Public License along  *
  19 *  with this program; if not, write to the Free Software Foundation, Inc.,  *
  20 *  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.              *
  21 *                                                                           *
  22 \***************************************************************************/
  23
  24 /* http://oauth.net/core/1.0a/ */
  25
  26 struct oauth_info;
  27
  28 /* Callback function called twice during the access token request process.
  29    Return FALSE if something broke and the process must be aborted. */
  30 typedef gboolean (*oauth_cb)( struct oauth_info * );
  31
  32 typedef enum
  33 {
  34         OAUTH_INIT,
  35         OAUTH_REQUEST_TOKEN,
  36         OAUTH_ACCESS_TOKEN,
  37 } oauth_stage_t;
  38
  39 struct oauth_info
  40 {
  41         oauth_stage_t stage;
  42         const struct oauth_service *sp;
  43
  44         oauth_cb func;
  45         void *data;
  46
  47         struct http_request *http;
  48
  49         char *auth_url;
  50         char *request_token;
  51
  52         char *token;
  53         char *token_secret;
  54         GSList *params;
  55 };
  56
  57 struct oauth_service
  58 {
  59         char *url_request_token;
  60         char *url_access_token;
  61         char *url_authorize;
  62
  63         char *consumer_key;
  64         char *consumer_secret;
  65 };
  66
  67 /* http://oauth.net/core/1.0a/#auth_step1 (section 6.1)
  68    Request an initial anonymous token which can be used to construct an
  69    authorization URL for the user. This is passed to the callback function
  70    in a struct oauth_info. */
  71 struct oauth_info *oauth_request_token( const struct oauth_service *sp, oauth_cb func, void *data );
  72
  73 /* http://oauth.net/core/1.0a/#auth_step3 (section 6.3)
  74    The user gets a PIN or so which we now exchange for the final access
  75    token. This is passed to the callback function in the same
  76    struct oauth_info. */
  77 gboolean oauth_access_token( const char *pin, struct oauth_info *st );
  78
  79 /* http://oauth.net/core/1.0a/#anchor12 (section 7)
  80    Generate an OAuth Authorization: HTTP header. access_token should be
  81    saved/fetched using the functions above. args can be a string with
  82    whatever's going to be in the POST body of the request. GET args will
  83    automatically be grabbed from url. */
  84 char *oauth_http_header( struct oauth_info *oi, const char *method, const char *url, char *args );
  85
  86 /* Shouldn't normally be required unless the process is aborted by the user. */
  87 void oauth_info_free( struct oauth_info *info );
  88
  89 /* Convert to and back from strings, for easier saving. */
  90 char *oauth_to_string( struct oauth_info *oi );
  91 struct oauth_info *oauth_from_string( char *in, const struct oauth_service *sp );
  92
  93 /* For reading misc. data. */
  94 void oauth_params_add( GSList **params, const char *key, const char *value );
  95 void oauth_params_parse( GSList **params, char *in );
  96 void oauth_params_free( GSList **params );
  97 char *oauth_params_string( GSList *params );
  98 void oauth_params_set( GSList **params, const char *key, const char *value );
  99 const char *oauth_params_get( GSList **params, const char *key );