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.

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.

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;

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.

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.

twitter_client_new_full ()

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

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.

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.

twitter_client_get_provider ()

TwitterProvider     twitter_client_get_provider         (TwitterClient *client);

Retrieves the type of provider used by client

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

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.

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.

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

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

twitter_client_get_public_timeline ()

gulong              twitter_client_get_public_timeline  (TwitterClient *client,
                                                         guint since_id);

twitter_client_get_friends_timeline ()

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

twitter_client_get_user_timeline ()

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

twitter_client_get_replies ()

gulong              twitter_client_get_replies          (TwitterClient *client);

twitter_client_get_favorites ()

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

twitter_client_get_archive ()

gulong              twitter_client_get_archive          (TwitterClient *client,
                                                         gint page);

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.

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.

twitter_client_get_status ()

gulong              twitter_client_get_status           (TwitterClient *client,
                                                         guint status_id);

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.

twitter_client_remove_status ()

gulong              twitter_client_remove_status        (TwitterClient *client,
                                                         guint status_id);

twitter_client_add_friend ()

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

twitter_client_remove_friend ()

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

twitter_client_follow_user ()

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

twitter_client_leave_user ()

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

twitter_client_add_favorite ()

gulong              twitter_client_add_favorite         (TwitterClient *client,
                                                         guint status_id);

twitter_client_remove_favorite ()

gulong              twitter_client_remove_favorite      (TwitterClient *client,
                                                         guint status_id);

The "base-url" property

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

The base URL of the Twitter service provider.

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

The "email" property

  "email"                    gchar*                : Read / Write

The email of the user, for authentication purposes.

Default value: NULL

The "max-requests" property

  "max-requests"             gint                  : Read

The amount of requests that can be performed.

Allowed values: >= G_MAXULONG

Default value: -1

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 "remaining-requests" property

  "remaining-requests"       gint                  : Read

The available requests that can be performed.

Allowed values: >= G_MAXULONG

Default value: -1

The "user-agent" property

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

The client name to be used when connecting.

Default value: NULL

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.

1
2
3
4
5

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.

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

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

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

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

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