signals.h File Reference
libpurple

Signal API. More...

`#include <glib.h>`
`#include "value.h"`

Go to the source code of this file.

## Macros

#define | PURPLE_CALLBACK(func) ((PurpleCallback)func)

## Typedefs

typedef void(* | PurpleCallback) (void)
typedef void(* | PurpleSignalMarshalFunc) (PurpleCallback cb, va_list args, void *data, void **return_val)

## Functions

Marshal Functions <br>
void | purple_marshal_VOID (PurpleCallback cb, va_list args, void *data, void **return_val)
void | purple_marshal_VOID__INT (PurpleCallback cb, va_list args, void *data, void **return_val)
void | purple_marshal_VOID__INT_INT (PurpleCallback cb, va_list args, void *data, void **return_val)
void | purple_marshal_VOID__POINTER (PurpleCallback cb, va_list args, void *data, void **return_val)
void | purple_marshal_VOID__POINTER_UINT (PurpleCallback cb, va_list args, void *data, void **return_val)
void | purple_marshal_VOID__POINTER_INT_INT (PurpleCallback cb, va_list args, void *data, void **return_val)
void | purple_marshal_VOID__POINTER_INT_POINTER (PurpleCallback cb, va_list args, void *data, void **return_val)
void | purple_marshal_VOID__POINTER_POINTER (PurpleCallback cb, va_list args, void *data, void **return_val)
void | purple_marshal_VOID__POINTER_POINTER_UINT (PurpleCallback cb, va_list args, void *data, void **return_val)
void | purple_marshal_VOID__POINTER_POINTER_UINT_UINT (PurpleCallback cb, va_list args, void *data, void **return_val)
void | purple_marshal_VOID__POINTER_POINTER_POINTER (PurpleCallback cb, va_list args, void *data, void **return_val)
void | purple_marshal_VOID__POINTER_POINTER_POINTER_POINTER (PurpleCallback cb, va_list args, void *data, void **return_val)
void | purple_marshal_VOID__POINTER_POINTER_POINTER_POINTER_POINTER (PurpleCallback cb, va_list args, void *data, void **return_val)
void | purple_marshal_VOID__POINTER_POINTER_POINTER_UINT (PurpleCallback cb, va_list args, void *data, void **return_val)
void | purple_marshal_VOID__POINTER_POINTER_POINTER_POINTER_UINT (PurpleCallback cb, va_list args, void *data, void **return_val)
void | purple_marshal_VOID__POINTER_POINTER_POINTER_UINT_UINT (PurpleCallback cb, va_list args, void *data, void **return_val)
void | purple_marshal_INT__INT (PurpleCallback cb, va_list args, void *data, void **return_val)
void | purple_marshal_INT__INT_INT (PurpleCallback cb, va_list args, void *data, void **return_val)
void | purple_marshal_INT__POINTER_POINTER (PurpleCallback cb, va_list args, void *data, void **return_val)
void | purple_marshal_INT__POINTER_POINTER_POINTER (PurpleCallback cb, va_list args, void *data, void **return_val)
void | purple_marshal_INT__POINTER_POINTER_POINTER_POINTER_POINTER (PurpleCallback cb, va_list args, void *data, void **return_val)
void | purple_marshal_BOOLEAN__POINTER (PurpleCallback cb, va_list args, void *data, void **return_val)
void | purple_marshal_BOOLEAN__POINTER_POINTER (PurpleCallback cb, va_list args, void *data, void **return_val)
void | purple_marshal_BOOLEAN__POINTER_BOOLEAN (PurpleCallback cb, va_list args, void *data, void **return_val)
void | purple_marshal_BOOLEAN__POINTER_POINTER_POINTER (PurpleCallback cb, va_list args, void *data, void **return_val)
void | purple_marshal_BOOLEAN__POINTER_POINTER_UINT (PurpleCallback cb, va_list args, void *data, void **return_val)
void | purple_marshal_BOOLEAN__POINTER_POINTER_POINTER_UINT (PurpleCallback cb, va_list args, void *data, void **return_val)
void | purple_marshal_BOOLEAN__POINTER_POINTER_POINTER_POINTER (PurpleCallback cb, va_list args, void *data, void **return_val)
void | purple_marshal_BOOLEAN__POINTER_POINTER_POINTER_POINTER_POINTER (PurpleCallback cb, va_list args, void *data, void **return_val)
void | purple_marshal_BOOLEAN__POINTER_POINTER_POINTER_POINTER_UINT (PurpleCallback cb, va_list args, void *data, void **return_val)
void | purple_marshal_BOOLEAN__POINTER_POINTER_POINTER_POINTER_POINTER_POINTER (PurpleCallback cb, va_list args, void *data, void **return_val)
void | purple_marshal_BOOLEAN__INT_POINTER (PurpleCallback cb, va_list args, void *data, void **return_val)
void | purple_marshal_POINTER__POINTER (PurpleCallback cb, va_list args, void *data, void **return_val)
void | purple_marshal_POINTER__POINTER_INT (PurpleCallback cb, va_list args, void *data, void **return_val)
void | purple_marshal_POINTER__POINTER_INT64 (PurpleCallback cb, va_list args, void *data, void **return_val)
void | purple_marshal_POINTER__POINTER_INT_BOOLEAN (PurpleCallback cb, va_list args, void *data, void **return_val)
void | purple_marshal_POINTER__POINTER_INT64_BOOLEAN (PurpleCallback cb, va_list args, void *data, void **return_val)
void | purple_marshal_POINTER__POINTER_POINTER (PurpleCallback cb, va_list args, void *data, void **return_val)

## Signal API <br>

#define | PURPLE_SIGNAL_PRIORITY_DEFAULT 0
| The priority of a signal connected using purple_signal_connect(). More...
#define | PURPLE_SIGNAL_PRIORITY_HIGHEST 9999
| The largest signal priority; signals with this priority will be called last. More...
#define | PURPLE_SIGNAL_PRIORITY_LOWEST -9999
| The smallest signal priority; signals with this priority will be called first. More...
gulong | purple_signal_register (void *instance, const char *signal, PurpleSignalMarshalFunc marshal, PurpleValue *ret_value, int num_values,...)
| Registers a signal in an instance. More...
void | purple_signal_unregister (void *instance, const char *signal)
| Unregisters a signal in an instance. More...
void | purple_signals_unregister_by_instance (void *instance)
| Unregisters all signals in an instance. More...
void | purple_signal_get_values (void *instance, const char *signal, PurpleValue **ret_value, int *num_values, PurpleValue ***values)
| Returns a list of value types used for a signal. More...
gulong | purple_signal_connect_priority (void *instance, const char *signal, void *handle, PurpleCallback func, void *data, int priority)
| Connects a signal handler to a signal for a particular object. More...
gulong | purple_signal_connect (void *instance, const char *signal, void *handle, PurpleCallback func, void *data)
| Connects a signal handler to a signal for a particular object. More...
gulong | purple_signal_connect_priority_vargs (void *instance, const char *signal, void *handle, PurpleCallback func, void *data, int priority)
| Connects a signal handler to a signal for a particular object. More...
gulong | purple_signal_connect_vargs (void *instance, const char *signal, void *handle, PurpleCallback func, void *data)
| Connects a signal handler to a signal for a particular object. More...
void | purple_signal_disconnect (void *instance, const char *signal, void *handle, PurpleCallback func)
| Disconnects a signal handler from a signal on an object. More...
void | purple_signals_disconnect_by_handle (void *handle)
| Removes all callbacks associated with a receiver handle. More...
void | purple_signal_emit (void *instance, const char *signal,...)
| Emits a signal. More...
void | purple_signal_emit_vargs (void *instance, const char *signal, va_list args)
| Emits a signal, using a va_list of arguments. More...
void * | purple_signal_emit_return_1 (void *instance, const char *signal,...)
| Emits a signal and returns the first non-NULL return value. More...
void * | purple_signal_emit_vargs_return_1 (void *instance, const char *signal, va_list args)
| Emits a signal and returns the first non-NULL return value. More...
void | purple_signals_init (void)
| Initializes the signals subsystem.
void | purple_signals_uninit (void)
| Uninitializes the signals subsystem.

## Detailed Description

Signal API.

Definition in file signals.h.

## Macro Definition Documentation

## PURPLE_SIGNAL_PRIORITY_DEFAULT

#define PURPLE_SIGNAL_PRIORITY_DEFAULT 0

The priority of a signal connected using purple_signal_connect().

See also
  purple_signal_connect_priority()

Definition at line 51 of file signals.h.

## PURPLE_SIGNAL_PRIORITY_HIGHEST

#define PURPLE_SIGNAL_PRIORITY_HIGHEST 9999

The largest signal priority; signals with this priority will be called last.

(This is highest as in numerical value, not as in order of importance.)

See also
  purple_signal_connect_priority().

Definition at line 58 of file signals.h.

## PURPLE_SIGNAL_PRIORITY_LOWEST

#define PURPLE_SIGNAL_PRIORITY_LOWEST -9999

The smallest signal priority; signals with this priority will be called first.

(This is lowest as in numerical value, not as in order of importance.)

See also
  purple_signal_connect_priority().

Definition at line 65 of file signals.h.

## Function Documentation

## purple_signal_connect()

gulong purple_signal_connect | ( | void * | instance,
|  | const char * | signal,
|  | void * | handle,
|  | PurpleCallback | func,
|  | void * | data
| ) |  |

Connects a signal handler to a signal for a particular object.

(Its priority defaults to 0, aka PURPLE_SIGNAL_PRIORITY_DEFAULT.)

Take care not to register a handler function twice. Purple will not correct any mistakes for you in this area.

Parameters

  instance | The instance to connect to.
  signal | The name of the signal to connect.
  handle | The handle of the receiver.
  func | The callback function.
  data | The data to pass to the callback function.

Returns
  The signal handler ID.

See also
  purple_signal_disconnect()

## purple_signal_connect_priority()

gulong purple_signal_connect_priority | ( | void * | instance,
|  | const char * | signal,
|  | void * | handle,
|  | PurpleCallback | func,
|  | void * | data,
|  | int | priority
| ) |  |

Connects a signal handler to a signal for a particular object.

Take care not to register a handler function twice. Purple will not correct any mistakes for you in this area.

Parameters

  instance | The instance to connect to.
  signal | The name of the signal to connect.
  handle | The handle of the receiver.
  func | The callback function.
  data | The data to pass to the callback function.
  priority | The priority with which the handler should be called. Signal handlers are called in ascending numerical order of priority from PURPLE_SIGNAL_PRIORITY_LOWEST to PURPLE_SIGNAL_PRIORITY_HIGHEST.

Returns
  The signal handler ID.

See also
  purple_signal_disconnect()

## purple_signal_connect_priority_vargs()

gulong purple_signal_connect_priority_vargs | ( | void * | instance,
|  | const char * | signal,
|  | void * | handle,
|  | PurpleCallback | func,
|  | void * | data,
|  | int | priority
| ) |  |

Connects a signal handler to a signal for a particular object.

The signal handler will take a va_args of arguments, instead of individual arguments.

Take care not to register a handler function twice. Purple will not correct any mistakes for you in this area.

Parameters

  instance | The instance to connect to.
  signal | The name of the signal to connect.
  handle | The handle of the receiver.
  func | The callback function.
  data | The data to pass to the callback function.
  priority | The priority with which the handler should be called. Signal handlers are called in ascending numerical order of priority from PURPLE_SIGNAL_PRIORITY_LOWEST to PURPLE_SIGNAL_PRIORITY_HIGHEST.

Returns
  The signal handler ID.

See also
  purple_signal_disconnect()

## purple_signal_connect_vargs()

gulong purple_signal_connect_vargs | ( | void * | instance,
|  | const char * | signal,
|  | void * | handle,
|  | PurpleCallback | func,
|  | void * | data
| ) |  |

Connects a signal handler to a signal for a particular object.

(Its priority defaults to 0, aka PURPLE_SIGNAL_PRIORITY_DEFAULT.)

The signal handler will take a va_args of arguments, instead of individual arguments.

Take care not to register a handler function twice. Purple will not correct any mistakes for you in this area.

Parameters

  instance | The instance to connect to.
  signal | The name of the signal to connect.
  handle | The handle of the receiver.
  func | The callback function.
  data | The data to pass to the callback function.

Returns
  The signal handler ID.

See also
  purple_signal_disconnect()

## purple_signal_disconnect()

void purple_signal_disconnect | ( | void * | instance,
|  | const char * | signal,
|  | void * | handle,
|  | PurpleCallback | func
| ) |  |

Disconnects a signal handler from a signal on an object.

Parameters

  instance | The instance to disconnect from.
  signal | The name of the signal to disconnect.
  handle | The handle of the receiver.
  func | The registered function to disconnect.

See also
  purple_signal_connect()

## purple_signal_emit()

void purple_signal_emit | ( | void * | instance,
|  | const char * | signal,
|  |  | ...
| ) |  |

Emits a signal.

Parameters

  instance | The instance emitting the signal.
  signal | The signal being emitted.

See also
  purple_signal_connect()
  purple_signal_disconnect()

## purple_signal_emit_return_1()

void* purple_signal_emit_return_1 | ( | void * | instance,
|  | const char * | signal,
|  |  | ...
| ) |  |

Emits a signal and returns the first non-NULL return value.

Further signal handlers are NOT called after a handler returns something other than NULL.

Parameters

  instance | The instance emitting the signal.
  signal | The signal being emitted.

Returns
  The first non-NULL return value

## purple_signal_emit_vargs()

void purple_signal_emit_vargs | ( | void * | instance,
|  | const char * | signal,
|  | va_list | args
| ) |  |

Emits a signal, using a va_list of arguments.

Parameters

  instance | The instance emitting the signal.
  signal | The signal being emitted.
  args | The arguments list.

See also
  purple_signal_connect()
  purple_signal_disconnect()

## purple_signal_emit_vargs_return_1()

void* purple_signal_emit_vargs_return_1 | ( | void * | instance,
|  | const char * | signal,
|  | va_list | args
| ) |  |

Emits a signal and returns the first non-NULL return value.

Further signal handlers are NOT called after a handler returns something other than NULL.

Parameters

  instance | The instance emitting the signal.
  signal | The signal being emitted.
  args | The arguments list.

Returns
  The first non-NULL return value

## purple_signal_get_values()

void purple_signal_get_values | ( | void * | instance,
|  | const char * | signal,
|  | PurpleValue ** | ret_value,
|  | int * | num_values,
|  | PurpleValue *** | values
| ) |  |

Returns a list of value types used for a signal.

Parameters

  instance | The instance the signal is registered to.
  signal | The signal.
  ret_value | The return value from the last signal handler.
  num_values | The returned number of values.
  values | The returned list of values.

## purple_signal_register()

gulong purple_signal_register | ( | void * | instance,
|  | const char * | signal,
|  | PurpleSignalMarshalFunc | marshal,
|  | PurpleValue * | ret_value,
|  | int | num_values,
|  |  | ...
| ) |  |

Registers a signal in an instance.

Parameters

  instance | The instance to register the signal for.
  signal | The signal name.
  marshal | The marshal function.
  ret_value | The return value type, or NULL for no return value.
  num_values | The number of values to be passed to the callbacks.
  ... | The values to pass to the callbacks.

Returns
  The signal ID local to that instance, or 0 if the signal couldn't be registered.

See also
  PurpleValue

## purple_signal_unregister()

void purple_signal_unregister | ( | void * | instance,
|  | const char * | signal
| ) |  |

Unregisters a signal in an instance.

Parameters

  instance | The instance to unregister the signal for.
  signal | The signal name.

## purple_signals_disconnect_by_handle()

void purple_signals_disconnect_by_handle | ( | void * | handle | ) |

Removes all callbacks associated with a receiver handle.

Parameters

  handle | The receiver handle.

## purple_signals_unregister_by_instance()

void purple_signals_unregister_by_instance | ( | void * | instance | ) |

Unregisters all signals in an instance.

Parameters

  instance | The instance to unregister the signal for.