eventloop.h File Reference
libpurple

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(). More...
typedef struct _PurpleEventLoopUiOps | PurpleEventLoopUiOps
| An abstraction of an application's mainloop; libpurple will use this to watch file descriptors and schedule timed callbacks. More...

## 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. More...
guint | purple_timeout_add_seconds (guint interval, GSourceFunc function, gpointer data)
| Creates a callback timer. More...
gboolean | purple_timeout_remove (guint handle)
| Removes a timeout handler. More...
guint | purple_input_add (int fd, PurpleInputCondition cond, PurpleInputFunction func, gpointer user_data)
| Adds an input handler. More...
gboolean | purple_input_remove (guint handle)
| Removes an input handler. More...
int | purple_input_get_error (int fd, int *error)
| Get the current error status for an input. More...
UI Registration Functions
void | purple_eventloop_set_ui_ops (PurpleEventLoopUiOps *ops)
| Sets the UI operations structure to be used for accounts. More...
PurpleEventLoopUiOps * | purple_eventloop_get_ui_ops (void)
| Returns the UI operations structure used for accounts. More...

## Detailed Description

Purple Event Loop API.

Definition in file eventloop.h.

## Typedef Documentation

typedef struct _PurpleEventLoopUiOps PurpleEventLoopUiOps

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

enum PurpleInputCondition

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.