eventloop.h File Reference

Purple Event Loop API. More...

#include <glib.h>

Go to the source code of this file.

Data Structures

struct  _PurpleEventLoopUiOps
 An abstraction of an application's mainloop; libpurple will use this to watch file descriptors and schedule timed callbacks. More...

Typedefs

typedef void(* PurpleInputFunction )(gpointer, gint, PurpleInputCondition)
 The type of callbacks to handle events on file descriptors, as passed to purple_input_add().
typedef struct
_PurpleEventLoopUiOps 
PurpleEventLoopUiOps

Enumerations

enum  PurpleInputCondition { PURPLE_INPUT_READ = 1 << 0, PURPLE_INPUT_WRITE = 1 << 1 }
 An input condition. More...

Functions

Event Loop API
guint purple_timeout_add (guint interval, GSourceFunc function, gpointer data)
 Creates a callback timer.
guint purple_timeout_add_seconds (guint interval, GSourceFunc function, gpointer data)
 Creates a callback timer.
gboolean purple_timeout_remove (guint handle)
 Removes a timeout handler.
guint purple_input_add (int fd, PurpleInputCondition cond, PurpleInputFunction func, gpointer user_data)
 Adds an input handler.
gboolean purple_input_remove (guint handle)
 Removes an input handler.
int purple_input_get_error (int fd, int *error)
 Get the current error status for an input.
UI Registration Functions
void purple_eventloop_set_ui_ops (PurpleEventLoopUiOps *ops)
 Sets the UI operations structure to be used for accounts.
PurpleEventLoopUiOpspurple_eventloop_get_ui_ops (void)
 Returns the UI operations structure used for accounts.


Detailed Description

Purple Event Loop API.

Definition in file eventloop.h.


Typedef Documentation

An abstraction of an application's mainloop; libpurple will use this to watch file descriptors and schedule timed callbacks.

If your application uses the glib mainloop, there is an implementation of this struct in libpurple/example/nullclient.c which you can use verbatim.

Definition at line 53 of file eventloop.h.

typedef void(* PurpleInputFunction)(gpointer, gint, PurpleInputCondition)

The type of callbacks to handle events on file descriptors, as passed to purple_input_add().

The callback will receive the user_data passed to purple_input_add(), the file descriptor on which the event occurred, and the condition that was satisfied to cause the callback to be invoked.

Definition at line 50 of file eventloop.h.


Enumeration Type Documentation

An input condition.

Enumerator:
PURPLE_INPUT_READ  A read condition.

PURPLE_INPUT_WRITE  A write condition.

Definition at line 38 of file eventloop.h.


Function Documentation

PurpleEventLoopUiOps* purple_eventloop_get_ui_ops ( void   ) 

Returns the UI operations structure used for accounts.

Returns:
The UI operations structure in use.

void purple_eventloop_set_ui_ops ( PurpleEventLoopUiOps ops  ) 

Sets the UI operations structure to be used for accounts.

Parameters:
ops The UI operations structure.

guint purple_input_add ( int  fd,
PurpleInputCondition  cond,
PurpleInputFunction  func,
gpointer  user_data 
)

Adds an input handler.

Parameters:
fd The input file descriptor.
cond The condition type.
func The callback function for data.
user_data User-specified data.
Returns:
The resulting handle (will be greater than 0).
See also:
g_io_add_watch_full

int purple_input_get_error ( int  fd,
int *  error 
)

Get the current error status for an input.

The return value and error follow getsockopt() with a level of SOL_SOCKET and an option name of SO_ERROR, and this is how the error is determined if the UI does not implement the input_get_error UI op.

Parameters:
fd The input file descriptor.
error A pointer to an int which on return will have the error, or 0 if no error.
Returns:
0 if there is no error; -1 if there is an error, in which case errno will be set.

gboolean purple_input_remove ( guint  handle  ) 

Removes an input handler.

Parameters:
handle The handle of the input handler. Note that this is the return value from purple_input_add(), not the file descriptor.

guint purple_timeout_add ( guint  interval,
GSourceFunc  function,
gpointer  data 
)

Creates a callback timer.

The timer will repeat until the function returns FALSE. The first call will be at the end of the first interval.

If the timer is in a multiple of seconds, use purple_timeout_add_seconds() instead as it allows UIs to group timers for power efficiency.

Parameters:
interval The time between calls of the function, in milliseconds.
function The function to call.
data data to pass to function.
Returns:
A handle to the timer which can be passed to purple_timeout_remove() to remove the timer.

guint purple_timeout_add_seconds ( guint  interval,
GSourceFunc  function,
gpointer  data 
)

Creates a callback timer.

The timer will repeat until the function returns FALSE. The first call will be at the end of the first interval.

This function allows UIs to group timers for better power efficiency. For this reason, interval may be rounded by up to a second.

Parameters:
interval The time between calls of the function, in seconds.
function The function to call.
data data to pass to function.
Returns:
A handle to the timer which can be passed to purple_timeout_remove() to remove the timer.
Since:
2.1.0

gboolean purple_timeout_remove ( guint  handle  ) 

Removes a timeout handler.

Parameters:
handle The handle, as returned by purple_timeout_add().
Returns:
TRUE if the handler was successfully removed.