Plugins/Purple Service/libpurple_extensions/fbapi.h
branchadium-1.5.11
changeset 6014 fcb71cb71a3d
parent 5941 307f53385811
parent 6013 f8d0dc659e3f
child 6016 325e2ab3406f
equal deleted inserted replaced
5941:307f53385811 6014:fcb71cb71a3d
     1 /*
       
     2  * libfacebook
       
     3  *
       
     4  * libfacebook is the property of its developers.  See the COPYRIGHT file
       
     5  * for more details.
       
     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 3 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, see <http://www.gnu.org/licenses/>.
       
    19  */
       
    20 
       
    21 #ifndef FBAPI_H
       
    22 #define FBAPI_H
       
    23 
       
    24 #ifdef __cplusplus
       
    25 extern "C" {
       
    26 #endif
       
    27 
       
    28 #include <glib.h>
       
    29 
       
    30 #include "connection.h"
       
    31 
       
    32 #define PURPLE_FBAPI_KEY "INSERT_KEY_HERE"
       
    33 
       
    34 typedef struct _PurpleFbApiCall PurpleFbApiCall;
       
    35 
       
    36 /**
       
    37  * This is the callback function when a response is received to an API
       
    38  * request.  The response will always be parsed as XML.
       
    39  *
       
    40  * error_message will be set if the physical TCP connection failed, or
       
    41  * if the API call returned <error_response> as the top level node in
       
    42  * the document.
       
    43  *
       
    44  * error will be set if and only if error_message is set.
       
    45  *
       
    46  * response will be null if error_message is non-null or if the
       
    47  * response was not valid XML.  So if error_message == NULL &&
       
    48  * response == NULL then you know the body was malformed XML.
       
    49  */
       
    50 typedef void (*PurpleFbApiCallback)(PurpleFbApiCall *apicall, gpointer user_data, const xmlnode *response, PurpleConnectionError error, const gchar *error_message);
       
    51 
       
    52 /**
       
    53  * Construct the body of a Facebook API request.
       
    54  *
       
    55  * @param account PurpleAccount of the user
       
    56  * @param method The API method to call.  For example, auth.getSession or
       
    57  *        events.get.
       
    58  * @param attrs key/value pairs of request arguments.  The list must be
       
    59  *        terminated with a NULL.  It should not contain the method,
       
    60  *        api_key, call_id, or sig parameters--these will be appended
       
    61  *        for you.
       
    62  */
       
    63 GString *purple_fbapi_construct_request(PurpleAccount *account, const char *method, ...) G_GNUC_NULL_TERMINATED;
       
    64 
       
    65 /**
       
    66  * @param account PurpleAccount of the user
       
    67  * @param args key/value pairs that will be POSTed to the API URL.  The
       
    68  *        list must be terminated with a NULL.  It should not contain
       
    69  *        the method, api_key, call_id, or sig parameters--these will be
       
    70  *        appended for you.
       
    71  * @see purple_fbapi_request
       
    72  */
       
    73 PurpleFbApiCall *purple_fbapi_request_vargs(PurpleAccount *account, PurpleFbApiCallback callback, gpointer user_data, GDestroyNotify user_data_destroy_func, const char *method, va_list args);
       
    74 
       
    75 /**
       
    76  * @param account PurpleAccount of the user
       
    77  * @param callback The callback function that should be called when we
       
    78  *        receive a response from the server.
       
    79  * @param user_data Optional data to pass to the callback function.
       
    80  * @param user_data_destroy_func An option function to be called and
       
    81  *        passed user_data to free it after this request has finished
       
    82  *        or been canceled.
       
    83  * @param method The API method to call.  For example, auth.getSession or
       
    84  *        events.get.
       
    85  * @param attrs key/value pairs that will be POSTed to the API URL.  The
       
    86  *        list must be terminated with a NULL.  It should not contain
       
    87  *        the method, api_key, call_id, or sig parameters--these will be
       
    88  *        appended for you.
       
    89  */
       
    90 PurpleFbApiCall *purple_fbapi_request(PurpleAccount *account, PurpleFbApiCallback callback, gpointer user_data, GDestroyNotify user_data_destroy_func, const char *method, ...) G_GNUC_NULL_TERMINATED;
       
    91 
       
    92 /*
       
    93  * Destroy a single pending API request.
       
    94  */
       
    95 void purple_fbapi_request_destroy(PurpleFbApiCall *apicall);
       
    96 
       
    97 /**
       
    98  * Destroy all pending API requests.
       
    99  */
       
   100 void purple_fbapi_uninit(void);
       
   101 
       
   102 #ifdef __cplusplus
       
   103 }
       
   104 #endif
       
   105 
       
   106 #endif /* FBAPI_H */