![]() |
![]() |
![]() |
Twitter-GLib Reference Manual | ![]() |
---|---|---|---|---|
Top | Description | Object Hierarchy | Properties | Signals |
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);
"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
"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
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.
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.
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.
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.
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.
|
class handler for the "authenticate" signal |
|
class handler for the "user-verified" signal |
|
class handler for the "session-eneded" signal |
|
class handler for the "status-received" signal |
|
class handler for the "user-received" signal |
|
class handler for the "timeline_complete" signal |
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
|
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.
|
the email address of the user |
|
the password of the user |
Returns : |
the newly created TwitterClient. Use g_object_unref()
to free the allocated resources
|
TwitterClient * twitter_client_new_full (TwitterProvider provider, const gchar *base_url, const gchar *email, const gchar *password);
|
|
|
|
|
|
|
|
Returns : |
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.
|
a TwitterClient |
|
the email address of the user |
|
the password of the 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.
|
a TwitterClient# |
|
return location for the email address, or NULL
|
|
return location for the password, or NULL
|
TwitterProvider twitter_client_get_provider (TwitterClient *client);
Retrieves the type of provider used by client
|
a TwitterClient |
Returns : |
the provider logical id |
const gchar * twitter_client_get_base_url (TwitterClient *client);
Retrieves the base URL of the service provider used by client
|
a TwitterClient |
Returns : |
the base URL. The returned string is owned by the TwitterClient and should never be modified of freed |
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.
|
a TwitterClient |
Returns : |
the handle of the request, or 0 |
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.
|
a TwitterClient |
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
|
a TwitterClient |
|
user ID or screen name |
Returns : |
the handle of the request, or 0 |
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
|
a TwitterClient |
|
E-mail address of the user |
Returns : |
the handle of the request, or 0 |
gulong twitter_client_get_public_timeline (TwitterClient *client, guint since_id);
|
|
|
|
Returns : |
gulong twitter_client_get_friends_timeline (TwitterClient *client, const gchar *friend_, gint64 since_date);
|
|
|
|
|
|
Returns : |
gulong twitter_client_get_user_timeline (TwitterClient *client, const gchar *user, guint count, gint64 since_date);
|
|
|
|
|
|
|
|
Returns : |
gulong twitter_client_get_replies (TwitterClient *client);
|
|
Returns : |
gulong twitter_client_get_favorites (TwitterClient *client, const gchar *user, gint page);
|
|
|
|
|
|
Returns : |
gulong twitter_client_get_archive (TwitterClient *client, gint page);
|
|
|
|
Returns : |
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.
|
a TwitterClient |
|
the user id or screen name |
|
the page number of the friends list |
|
TRUE if the TwitterUser should not have
the last status associated to them
|
Returns : |
the handle of the request, or 0 |
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.
|
a TwitterClient |
|
the page number of the followers list |
|
TRUE if the TwitterUser should not have
the last status associated to them
|
Returns : |
the handle of the request, or 0 |
gulong twitter_client_get_status (TwitterClient *client, guint status_id);
|
|
|
|
Returns : |
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
.
|
a TwitterClient |
|
the text of the status message |
Returns : |
the handle of the request, or 0 |
gulong twitter_client_remove_status (TwitterClient *client, guint status_id);
|
|
|
|
Returns : |
gulong twitter_client_add_friend (TwitterClient *client, const gchar *user);
|
|
|
|
Returns : |
gulong twitter_client_remove_friend (TwitterClient *client, const gchar *user);
|
|
|
|
Returns : |
gulong twitter_client_follow_user (TwitterClient *client, const gchar *user);
|
|
|
|
Returns : |
gulong twitter_client_leave_user (TwitterClient *client, const gchar *user);
|
|
|
|
Returns : |
gulong twitter_client_add_favorite (TwitterClient *client, guint status_id);
|
|
|
|
Returns : |
gulong twitter_client_remove_favorite (TwitterClient *client, guint status_id);
|
|
|
|
Returns : |
"base-url"
property"base-url" gchar* : Read / Write / Construct Only
The base URL of the Twitter service provider.
Default value: "http://twitter.com"
"email"
property"email" gchar* : Read / Write
The email of the user, for authentication purposes.
Default value: NULL
"password"
property"password" gchar* : Read / Write
The password of the user, for authentication purposes.
Default value: NULL
"provider"
property"provider" TwitterProvider : Read / Write / Construct Only
The Twitter service provider.
Default value: TWITTER_DEFAULT_PROVIDER
"user-agent"
property"user-agent" gchar* : Read / Write / Construct Only
The client name to be used when connecting.
Default value: NULL
"authenticate"
signalgboolean 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.
|
the TwitterClient that received the signal |
|
the state of the authentication process |
|
user data set when the signal handler was connected. |
Returns : |
TRUE if the user credentials were correctly set
|
"session-ended"
signalvoid 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 TwitterClient that emitted the signal |
|
user data set when the signal handler was connected. |
"status-received"
signalvoid 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 TwitterClient that emitted the signal |
|
the handle of the request |
|
a TwitterStatus |
|
set to a GError in case of error |
|
user data set when the signal handler was connected. |
"timeline-complete"
signalvoid 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 TwitterClient that emitted the signal |
|
user data set when the signal handler was connected. |
"user-received"
signalvoid 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 TwitterClient that emitted the signal |
|
the handle of the request |
|
a TwitterUser |
|
set to a GError in case of error |
|
user data set when the signal handler was connected. |
"user-verified"
signalvoid 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
|
the TwitterClient that emitted the signal |
|
the handle of the request |
|
whether the user credentials are verified |
|
set to a GError in case of error |
|
user data set when the signal handler was connected. |