TwitterClient

TwitterClient — Wrapper for the Twitter API

Synopsis

enum                TwitterProvider;
enum                TwitterAuthState;
                    TwitterClient;
                    TwitterClientClass;
TwitterClient *     twitter_client_new                  (void);
TwitterClient *     twitter_client_new_for_user         (const gchar *email,
                                                         const gchar *password);
TwitterClient *     twitter_client_new_full             (TwitterProvider provider,
                                                         const gchar *base_url,
                                                         const gchar *email,
                                                         const gchar *password);
void                twitter_client_set_user             (TwitterClient *client,
                                                         const gchar *email,
                                                         const gchar *password);
void                twitter_client_get_user             (TwitterClient *client,
                                                         gchar **email,
                                                         gchar **password);
TwitterProvider     twitter_client_get_provider         (TwitterClient *client);
const gchar *       twitter_client_get_base_url         (TwitterClient *client);

gulong              twitter_client_verify_user          (TwitterClient *client);
void                twitter_client_end_session          (TwitterClient *client);

gulong              twitter_client_show_user_from_id    (TwitterClient *client,
                                                         const gchar *id_or_screen_name);
gulong              twitter_client_show_user_from_email (TwitterClient *client,
                                                         const gchar *email);

gulong              twitter_client_get_public_timeline  (TwitterClient *client,
                                                         guint since_id);
gulong              twitter_client_get_friends_timeline (TwitterClient *client,
                                                         const gchar *friend_,
                                                         gint64 since_date);
gulong              twitter_client_get_user_timeline    (TwitterClient *client,
                                                         const gchar *user,
                                                         guint count,
                                                         gint64 since_date);
gulong              twitter_client_get_replies          (TwitterClient *client);
gulong              twitter_client_get_favorites        (TwitterClient *client,
                                                         const gchar *user,
                                                         gint page);
gulong              twitter_client_get_archive          (TwitterClient *client,
                                                         gint page);
gulong              twitter_client_get_friends          (TwitterClient *client,
                                                         const gchar *user,
                                                         gint page,
                                                         gboolean omit_status);
gulong              twitter_client_get_followers        (TwitterClient *client,
                                                         gint page,
                                                         gboolean omit_status);

gulong              twitter_client_get_status           (TwitterClient *client,
                                                         guint status_id);
gulong              twitter_client_add_status           (TwitterClient *client,
                                                         const gchar *text);
gulong              twitter_client_remove_status        (TwitterClient *client,
                                                         guint status_id);

gulong              twitter_client_add_friend           (TwitterClient *client,
                                                         const gchar *user);
gulong              twitter_client_remove_friend        (TwitterClient *client,
                                                         const gchar *user);
gulong              twitter_client_follow_user          (TwitterClient *client,
                                                         const gchar *user);
gulong              twitter_client_leave_user           (TwitterClient *client,
                                                         const gchar *user);
gulong              twitter_client_add_favorite         (TwitterClient *client,
                                                         guint status_id);
gulong              twitter_client_remove_favorite      (TwitterClient *client,
                                                         guint status_id);

Object Hierarchy

  GObject
   +----TwitterClient

Properties

  "base-url"                 gchar*                : Read / Write / Construct Only
  "email"                    gchar*                : Read / Write
  "password"                 gchar*                : Read / Write
  "provider"                 TwitterProvider       : Read / Write / Construct Only
  "user-agent"               gchar*                : Read / Write / Construct Only

Signals

  "authenticate"                                   : Run Last / No Recursion
  "session-ended"                                  : Run Last
  "status-received"                                : Run Last
  "timeline-complete"                              : Run Last
  "user-received"                                  : Run Last
  "user-verified"                                  : Run Last

Description

TwitterClient is the main object wrapping the details of the Twitter RESTful API.

In order to use Twitter through TwitterClient, a new instance should be created using twitter_client_new() or twitter_client_new_for_user(). TwitterClient handles every operation asynchronously, thus requiring a GMainLoop running. Every result will emit one of the TwitterClient signals; in case of error, the GError parameter of the signals will be set.

Authentication is handled automatically by setting the "email" and "password" properties. These two properties can be set at construction time or by using twitter_client_set_user(). Interactive authentication can be implemented by using the "authenticate" signal as well: when the signal passes the TwitterAuthState value or TWITTER_AUTH_NEGOTIATING the handler should set the user credentials with twitter_client_set_user(); in case of error, the ::authenticate signal will use TWITTER_AUTH_RETRY until the authentication succeeds or the signal handler returns FALSE, in which case the TWITTER_AUTH_FAILED state will be used.

Details

enum TwitterProvider

typedef enum { /*< prefix=TWITTER >*/
  TWITTER_CUSTOM_PROVIDER = 0,
  TWITTER_DEFAULT_PROVIDER,
  TWITTER_IDENTI_CA
} TwitterProvider;

The provider for the Twitter services.

TWITTER_DEFAULT_PROVIDER is the default provider, at http://twitter.com.

TWITTER_IDENTI_CA is the identi.ca Twitter compatibility provider, at http://identi.ca/api.

TWITTER_CUSTOM_PROVIDER is used with twitter_client_set_base_url() for custom Twitter services providing a Twitter compatibility layer

This enumeration can be extended at any later date.

TWITTER_CUSTOM_PROVIDER

 A custom provider

TWITTER_DEFAULT_PROVIDER

 The default Twitter provider

TWITTER_IDENTI_CA

 The Identi.ca provider

enum TwitterAuthState

typedef enum {
  TWITTER_AUTH_NEGOTIATING,
  TWITTER_AUTH_RETRY,
  TWITTER_AUTH_FAILED,
  TWITTER_AUTH_SUCCESS
} TwitterAuthState;

Enumeration used to distinguish the states of the authentication process in the "authenticate" signal handlers.

TWITTER_AUTH_NEGOTIATING

 Initial phase of the authentication

TWITTER_AUTH_RETRY

 Retry the authentication

TWITTER_AUTH_FAILED

 Authentication failed

TWITTER_AUTH_SUCCESS

 Authentication succeded

TwitterClient

typedef struct _TwitterClient TwitterClient;

TwitterClient allows to connect to the Twitter web service and operate using the RESTful API provided from any GLib-based application.

The TwitterClient struct contains private data only, and should only be accessed using the functions below.

TwitterClientClass

typedef struct {
  gboolean (* authenticate)      (TwitterClient    *client,
                                  TwitterAuthState  state);

  void     (* user_verified)     (TwitterClient    *client,
                                  gulong            handle,
                                  gboolean          is_verified,
                                  const GError     *error);
  void     (* session_ended)     (TwitterClient    *client);

  void     (* status_received)   (TwitterClient    *client,
                                  gulong            handle,
                                  TwitterStatus    *status,
                                  const GError     *error);
  void     (* user_received)     (TwitterClient    *client,
                                  gulong            handle,
                                  TwitterUser      *user,
                                  const GError     *error);

  void     (* timeline_complete) (TwitterClient    *client);
} TwitterClientClass;

Base class for TwitterClient.

authenticate ()

 class handler for the "authenticate" signal

user_verified ()

 class handler for the "user-verified" signal

session_ended ()

 class handler for the "session-eneded" signal

status_received ()

 class handler for the "status-received" signal

user_received ()

 class handler for the "user-received" signal

timeline_complete ()

 class handler for the "timeline_complete" signal

twitter_client_new ()

TwitterClient *     twitter_client_new                  (void);

Creates a new TwitterClient using the default provider.

It is possible to use the "authenticate" signal to handle the authentication interactively when needed, or to use twitter_client_set_user() to set the user credentials.

Returns :

 the newly created TwitterClient. Use g_object_unref() to free the allocated resources

twitter_client_new_for_user ()

TwitterClient *     twitter_client_new_for_user         (const gchar *email,
                                                         const gchar *password);

Creates a new TwitterClient using the default provider, and sets the credentials of the user.

email :

 the email address of the user

password :

 the password of the user

Returns :

 the newly created TwitterClient. Use g_object_unref() to free the allocated resources

twitter_client_new_full ()

TwitterClient *     twitter_client_new_full             (TwitterProvider provider,
                                                         const gchar *base_url,
                                                         const gchar *email,
                                                         const gchar *password);

provider :

base_url :

email :

password :

Returns :

twitter_client_set_user ()

void                twitter_client_set_user             (TwitterClient *client,
                                                         const gchar *email,
                                                         const gchar *password);

Sets the user credentials of the user. The [ email, password ] tuple will be used to authenticate the client whenever a request requiring authentication is queued.

client :

 a TwitterClient

email :

 the email address of the user

password :

 the password of the user

twitter_client_get_user ()

void                twitter_client_get_user             (TwitterClient *client,
                                                         gchar **email,
                                                         gchar **password);

Retrieves the user credentials.

The returned strings are newly allocated and should be freed using g_free() when done using them.

client :

 a TwitterClient#

email :

 return location for the email address, or NULL

password :

 return location for the password, or NULL

twitter_client_get_provider ()

TwitterProvider     twitter_client_get_provider         (TwitterClient *client);

Retrieves the type of provider used by client

client :

 a TwitterClient

Returns :

 the provider logical id

twitter_client_get_base_url ()

const gchar *       twitter_client_get_base_url         (TwitterClient *client);

Retrieves the base URL of the service provider used by client

client :

 a TwitterClient

Returns :

 the base URL. The returned string is owned by the TwitterClient and should never be modified of freed

twitter_client_verify_user ()

gulong              twitter_client_verify_user          (TwitterClient *client);

Requests a verification of the user credentials used by client to the provider.

The "user-verified" signal will be emitted with the results of the request.

client :

 a TwitterClient

Returns :

 the handle of the request, or 0

twitter_client_end_session ()

void                twitter_client_end_session          (TwitterClient *client);

Ends the current session of client. The authentication state will be reset.

The "session-ended" signal will be emitted when the provider acknowledged the request.

client :

 a TwitterClient

twitter_client_show_user_from_id ()

gulong              twitter_client_show_user_from_id    (TwitterClient *client,
                                                         const gchar *id_or_screen_name);

Requests the provider used by client to "show" the user matching the user string.

The user string is either the user id as returned by twitter_user_get_id(), or the screen name as returned by twitter_user_get_screen_name().

The "user-received" signal will be emitted with the requested TwitterUser

client :

 a TwitterClient

id_or_screen_name :

 user ID or screen name

Returns :

 the handle of the request, or 0

twitter_client_show_user_from_email ()

gulong              twitter_client_show_user_from_email (TwitterClient *client,
                                                         const gchar *email);

Requests the provider used by client to "show" the user matching the email string.

The "user-received" signal will be emitted with the requested TwitterUser

client :

 a TwitterClient

email :

 E-mail address of the user

Returns :

 the handle of the request, or 0

twitter_client_get_public_timeline ()

gulong              twitter_client_get_public_timeline  (TwitterClient *client,
                                                         guint since_id);

client :

since_id :

Returns :

twitter_client_get_friends_timeline ()

gulong              twitter_client_get_friends_timeline (TwitterClient *client,
                                                         const gchar *friend_,
                                                         gint64 since_date);

client :

friend_ :

since_date :

Returns :

twitter_client_get_user_timeline ()

gulong              twitter_client_get_user_timeline    (TwitterClient *client,
                                                         const gchar *user,
                                                         guint count,
                                                         gint64 since_date);

client :

user :

count :

since_date :

Returns :

twitter_client_get_replies ()

gulong              twitter_client_get_replies          (TwitterClient *client);

client :

Returns :

twitter_client_get_favorites ()

gulong              twitter_client_get_favorites        (TwitterClient *client,
                                                         const gchar *user,
                                                         gint page);

client :

user :

page :

Returns :

twitter_client_get_archive ()

gulong              twitter_client_get_archive          (TwitterClient *client,
                                                         gint page);

client :

page :

Returns :

twitter_client_get_friends ()

gulong              twitter_client_get_friends          (TwitterClient *client,
                                                         const gchar *user,
                                                         gint page,
                                                         gboolean omit_status);

Requests the provider used by client for a (paged) list of the people followed by the TwitterClient authenticated user.

The "user-received" signal will be emitted for each followed user.

client :

 a TwitterClient

user :

 the user id or screen name

page :

 the page number of the friends list

omit_status :

 TRUE if the TwitterUser should not have the last status associated to them

Returns :

 the handle of the request, or 0

twitter_client_get_followers ()

gulong              twitter_client_get_followers        (TwitterClient *client,
                                                         gint page,
                                                         gboolean omit_status);

Requests the provider used by client for a (paged) list of the people following the TwitterClient authenticated user.

The "user-received" signal will be emitted for each follower.

client :

 a TwitterClient

page :

 the page number of the followers list

omit_status :

 TRUE if the TwitterUser should not have the last status associated to them

Returns :

 the handle of the request, or 0

twitter_client_get_status ()

gulong              twitter_client_get_status           (TwitterClient *client,
                                                         guint status_id);

client :

status_id :

Returns :

twitter_client_add_status ()

gulong              twitter_client_add_status           (TwitterClient *client,
                                                         const gchar *text);

Adds text to the status messages of the user currently authenticated by client.

The "status-received" signal will be emitted with the TwitterStatus for text.

client :

 a TwitterClient

text :

 the text of the status message

Returns :

 the handle of the request, or 0

twitter_client_remove_status ()

gulong              twitter_client_remove_status        (TwitterClient *client,
                                                         guint status_id);

client :

status_id :

Returns :

twitter_client_add_friend ()

gulong              twitter_client_add_friend           (TwitterClient *client,
                                                         const gchar *user);

client :

user :

Returns :

twitter_client_remove_friend ()

gulong              twitter_client_remove_friend        (TwitterClient *client,
                                                         const gchar *user);

client :

user :

Returns :

twitter_client_follow_user ()

gulong              twitter_client_follow_user          (TwitterClient *client,
                                                         const gchar *user);

client :

user :

Returns :

twitter_client_leave_user ()

gulong              twitter_client_leave_user           (TwitterClient *client,
                                                         const gchar *user);

client :

user :

Returns :

twitter_client_add_favorite ()

gulong              twitter_client_add_favorite         (TwitterClient *client,
                                                         guint status_id);

client :

status_id :

Returns :

twitter_client_remove_favorite ()

gulong              twitter_client_remove_favorite      (TwitterClient *client,
                                                         guint status_id);

client :

status_id :

Returns :

Property Details

The "base-url" property

  "base-url"                 gchar*                : Read / Write / Construct Only

The base URL of the Twitter service provider.

Default value: "http://twitter.com"

The "email" property

  "email"                    gchar*                : Read / Write

The email of the user, for authentication purposes.

Default value: NULL

The "password" property

  "password"                 gchar*                : Read / Write

The password of the user, for authentication purposes.

Default value: NULL

The "provider" property

  "provider"                 TwitterProvider       : Read / Write / Construct Only

The Twitter service provider.

Default value: TWITTER_DEFAULT_PROVIDER

The "user-agent" property

  "user-agent"               gchar*                : Read / Write / Construct Only

The client name to be used when connecting.

Default value: NULL

Signal Details

The "authenticate" signal

gboolean            user_function                      (TwitterClient   *client,
                                                        TwitterAuthState state,
                                                        gpointer         user_data)      : Run Last / No Recursion

Handles the authentication of the user onto the Twitter services.

The authentication can be a multi-state process. If the user's credentials were not set before issuing a command that requires authentication, the ::authenticate signal will be emitted with the TWITTER_AUTH_NEGOTIATING state. In this case, the credentials must be set and the handler must return TRUE. 

  if (state == TWITTER_AUTH_NEGOTIATING)
    {
      twitter_client_set_user (client, email, password);
      return TRUE;
    }

In case of failed authentication, the TWITTER_AUTH_RETRY state will be used until the handler sets the correct credentials and returns TRUE or aborts the authentication process and returns FALSE; in the latter case, the signal will be emitted one last time with the TWITTER_AUTH_FAILED state.

If the authentication was successful, the signal will be emitted with the TWITTER_AUTH_SUCCESS state.

client :

 the TwitterClient that received the signal

state :

 the state of the authentication process

user_data :

 user data set when the signal handler was connected.

Returns :

 TRUE if the user credentials were correctly set

The "session-ended" signal

void                user_function                      (TwitterClient *client,
                                                        gpointer       user_data)      : Run Last

The ::session-ended signal is emitted at the end of the twitter_client_end_session() request

client :

 the TwitterClient that emitted the signal

user_data :

 user data set when the signal handler was connected.

The "status-received" signal

void                user_function                      (TwitterClient *client,
                                                        gulong         handle,
                                                        TwitterStatus *user,
                                                        gpointer       error,
                                                        gpointer       user_data)      : Run Last

The ::status-received signal is emitted each time client receives a TwitterStatus from the provider.

In case of error, error will be set to the appropriate GError; otherwise, it will be NULL

client :

 the TwitterClient that emitted the signal

handle :

 the handle of the request

user :

 a TwitterStatus

error :

 set to a GError in case of error

user_data :

 user data set when the signal handler was connected.

The "timeline-complete" signal

void                user_function                      (TwitterClient *client,
                                                        gpointer       user_data)      : Run Last

The ::timeline-complete signal is emitted at the end of a timeline request to the provider

client :

 the TwitterClient that emitted the signal

user_data :

 user data set when the signal handler was connected.

The "user-received" signal

void                user_function                      (TwitterClient *client,
                                                        gulong         handle,
                                                        TwitterUser   *user,
                                                        gpointer       error,
                                                        gpointer       user_data)      : Run Last

The ::user-received signal is emitted each time client receives a TwitterUser from the provider.

In case of error, error will be set to the appropriate GError; otherwise, it will be NULL

client :

 the TwitterClient that emitted the signal

handle :

 the handle of the request

user :

 a TwitterUser

error :

 set to a GError in case of error

user_data :

 user data set when the signal handler was connected.

The "user-verified" signal

void                user_function                      (TwitterClient *client,
                                                        gulong         handle,
                                                        gboolean       is_verified,
                                                        gpointer       error,
                                                        gpointer       user_data)        : Run Last

The ::user-verified signal is emitted by client after twitter_client_verify_user() has been called.

The is_verified argument will be set to TRUE of FALSE depending on the result of the verification. In case of error, error will be set to the appropriate GError; otherwise it will be NULL

client :

 the TwitterClient that emitted the signal

handle :

 the handle of the request

is_verified :

 whether the user credentials are verified

error :

 set to a GError in case of error

user_data :

 user data set when the signal handler was connected.
Generated by GTK-Doc V1.11