pounce.h File Reference
libpurple

Buddy Pounce API. More...

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

Go to the source code of this file.

## Data Structures

struct | _PurplePounce
| A buddy pounce structure. More...

## Typedefs

typedef struct _PurplePounce | PurplePounce
typedef void(* | PurplePounceCb) (PurplePounce *, PurplePounceEvent, void *)
| A pounce callback. More...

## Enumerations

enum | PurplePounceEvent { PURPLE_POUNCE_NONE = 0x000, PURPLE_POUNCE_SIGNON = 0x001, PURPLE_POUNCE_SIGNOFF = 0x002, PURPLE_POUNCE_AWAY = 0x004, PURPLE_POUNCE_AWAY_RETURN = 0x008, PURPLE_POUNCE_IDLE = 0x010, PURPLE_POUNCE_IDLE_RETURN = 0x020, PURPLE_POUNCE_TYPING = 0x040, PURPLE_POUNCE_TYPED = 0x080, PURPLE_POUNCE_TYPING_STOPPED = 0x100, PURPLE_POUNCE_MESSAGE_RECEIVED = 0x200 }
| Events that trigger buddy pounces. More...
enum | PurplePounceOption { PURPLE_POUNCE_OPTION_NONE = 0x00, PURPLE_POUNCE_OPTION_AWAY = 0x01 }

## Functions

Buddy Pounce API
PurplePounce * | purple_pounce_new (const char *ui_type, PurpleAccount *pouncer, const char *pouncee, PurplePounceEvent event, PurplePounceOption option)
| Creates a new buddy pounce. More...
void | purple_pounce_destroy (PurplePounce *pounce)
| Destroys a buddy pounce. More...
void | purple_pounce_destroy_all_by_account (PurpleAccount *account)
| Destroys all buddy pounces for the account. More...
void | purple_pounce_destroy_all_by_buddy (PurpleBuddy *buddy)
| Destroys all buddy pounces for a buddy. More...
void | purple_pounce_set_events (PurplePounce *pounce, PurplePounceEvent events)
| Sets the events a pounce should watch for. More...
void | purple_pounce_set_options (PurplePounce *pounce, PurplePounceOption options)
| Sets the options for a pounce. More...
void | purple_pounce_set_pouncer (PurplePounce *pounce, PurpleAccount *pouncer)
| Sets the account that will do the pouncing. More...
void | purple_pounce_set_pouncee (PurplePounce *pounce, const char *pouncee)
| Sets the buddy a pounce should pounce on. More...
void | purple_pounce_set_save (PurplePounce *pounce, gboolean save)
| Sets whether or not the pounce should be saved after execution. More...
void | purple_pounce_action_register (PurplePounce *pounce, const char *name)
| Registers an action type for the pounce. More...
void | purple_pounce_action_set_enabled (PurplePounce *pounce, const char *action, gboolean enabled)
| Enables or disables an action for a pounce. More...
void | purple_pounce_action_set_attribute (PurplePounce *pounce, const char *action, const char *attr, const char *value)
| Sets a value for an attribute in an action. More...
void | purple_pounce_set_data (PurplePounce *pounce, void *data)
| Sets the pounce-specific data. More...
PurplePounceEvent | purple_pounce_get_events (const PurplePounce *pounce)
| Returns the events a pounce should watch for. More...
PurplePounceOption | purple_pounce_get_options (const PurplePounce *pounce)
| Returns the options for a pounce. More...
PurpleAccount * | purple_pounce_get_pouncer (const PurplePounce *pounce)
| Returns the account that will do the pouncing. More...
const char * | purple_pounce_get_pouncee (const PurplePounce *pounce)
| Returns the buddy a pounce should pounce on. More...
gboolean | purple_pounce_get_save (const PurplePounce *pounce)
| Returns whether or not the pounce should save after execution. More...
gboolean | purple_pounce_action_is_enabled (const PurplePounce *pounce, const char *action)
| Returns whether or not an action is enabled. More...
const char * | purple_pounce_action_get_attribute (const PurplePounce *pounce, const char *action, const char *attr)
| Returns the value for an attribute in an action. More...
void * | purple_pounce_get_data (const PurplePounce *pounce)
| Returns the pounce-specific data. More...
void | purple_pounce_execute (const PurpleAccount *pouncer, const char *pouncee, PurplePounceEvent events)
| Executes a pounce with the specified pouncer, pouncee, and event type. More...
Buddy Pounce Subsystem API
PurplePounce * | purple_find_pounce (const PurpleAccount *pouncer, const char *pouncee, PurplePounceEvent events)
| Finds a pounce with the specified event(s) and buddy. More...
gboolean | purple_pounces_load (void)
| Loads the pounces. More...
void | purple_pounces_register_handler (const char *ui, PurplePounceCb cb, void(*new_pounce)(PurplePounce *pounce), void(*free_pounce)(PurplePounce *pounce))
| Registers a pounce handler for a UI. More...
void | purple_pounces_unregister_handler (const char *ui)
| Unregisters a pounce handle for a UI. More...
GList * | purple_pounces_get_all (void)
| Returns a list of all registered buddy pounces. More...
GList * | purple_pounces_get_all_for_ui (const char *ui)
| Returns a list of registered buddy pounces for the ui-type. More...
void * | purple_pounces_get_handle (void)
| Returns the buddy pounce subsystem handle. More...
void | purple_pounces_init (void)
| Initializes the pounces subsystem.
void | purple_pounces_uninit (void)
| Uninitializes the pounces subsystem.

## Detailed Description

Buddy Pounce API.

Definition in file pounce.h.

## Typedef Documentation

## PurplePounceCb

typedef void(* PurplePounceCb) (PurplePounce *, PurplePounceEvent, void *)

A pounce callback.

Definition at line 60 of file pounce.h.

## Enumeration Type Documentation

## PurplePounceEvent

enum PurplePounceEvent

Events that trigger buddy pounces.

Enumerator
PURPLE_POUNCE_NONE | No events.
PURPLE_POUNCE_SIGNON | The buddy signed on.
PURPLE_POUNCE_SIGNOFF | The buddy signed off.
PURPLE_POUNCE_AWAY | The buddy went away.
PURPLE_POUNCE_AWAY_RETURN | The buddy returned from away.
PURPLE_POUNCE_IDLE | The buddy became idle.
PURPLE_POUNCE_IDLE_RETURN | The buddy is no longer idle.
PURPLE_POUNCE_TYPING | The buddy started typing.
PURPLE_POUNCE_TYPED | The buddy has entered text.
PURPLE_POUNCE_TYPING_STOPPED | The buddy stopped typing.
PURPLE_POUNCE_MESSAGE_RECEIVED | The buddy sent a message.

Definition at line 37 of file pounce.h.

## PurplePounceOption

enum PurplePounceOption

Enumerator
PURPLE_POUNCE_OPTION_NONE | No Option.
PURPLE_POUNCE_OPTION_AWAY | Pounce only when away.

Definition at line 53 of file pounce.h.

## Function Documentation

## purple_find_pounce()

PurplePounce* purple_find_pounce | ( | const PurpleAccount * | pouncer,
|  | const char * | pouncee,
|  | PurplePounceEvent | events
| ) |  |

Finds a pounce with the specified event(s) and buddy.

Parameters

  pouncer | The account to match against.
  pouncee | The buddy to match against.
  events | The event(s) to match against.

Returns
  The pounce if found, or `NULL` otherwise.

## purple_pounce_action_get_attribute()

const char* purple_pounce_action_get_attribute | ( | const PurplePounce * | pounce,
|  | const char * | action,
|  | const char * | attr
| ) |  |

Returns the value for an attribute in an action.

Parameters

  pounce | The buddy pounce.
  action | The action name.
  attr | The attribute name.

Returns
  The attribute value, if it exists, or `NULL`.

## purple_pounce_action_is_enabled()

gboolean purple_pounce_action_is_enabled | ( | const PurplePounce * | pounce,
|  | const char * | action
| ) |  |

Returns whether or not an action is enabled.

Parameters

  pounce | The buddy pounce.
  action | The action name.

Returns
  `TRUE` if the action is enabled, or `FALSE` otherwise.

## purple_pounce_action_register()

void purple_pounce_action_register | ( | PurplePounce * | pounce,
|  | const char * | name
| ) |  |

Registers an action type for the pounce.

Parameters

  pounce | The buddy pounce.
  name | The action name.

## purple_pounce_action_set_attribute()

void purple_pounce_action_set_attribute | ( | PurplePounce * | pounce,
|  | const char * | action,
|  | const char * | attr,
|  | const char * | value
| ) |  |

Sets a value for an attribute in an action.

If value is `NULL`, the value will be unset.

Parameters

  pounce | The buddy pounce.
  action | The action name.
  attr | The attribute name.
  value | The value.

## purple_pounce_action_set_enabled()

void purple_pounce_action_set_enabled | ( | PurplePounce * | pounce,
|  | const char * | action,
|  | gboolean | enabled
| ) |  |

Enables or disables an action for a pounce.

Parameters

  pounce | The buddy pounce.
  action | The name of the action.
  enabled | The enabled state.

## purple_pounce_destroy()

void purple_pounce_destroy | ( | PurplePounce * | pounce | ) |

Destroys a buddy pounce.

Parameters

  pounce | The buddy pounce.

## purple_pounce_destroy_all_by_account()

void purple_pounce_destroy_all_by_account | ( | PurpleAccount * | account | ) |

Destroys all buddy pounces for the account.

Parameters

  account | The account to remove all pounces from.

## purple_pounce_destroy_all_by_buddy()

void purple_pounce_destroy_all_by_buddy | ( | PurpleBuddy * | buddy | ) |

Destroys all buddy pounces for a buddy.

Parameters

  buddy | The buddy whose pounces are to be removed

Since
  2.8.0

## purple_pounce_execute()

void purple_pounce_execute | ( | const PurpleAccount * | pouncer,
|  | const char * | pouncee,
|  | PurplePounceEvent | events
| ) |  |

Executes a pounce with the specified pouncer, pouncee, and event type.

Parameters

  pouncer | The account that will do the pouncing.
  pouncee | The buddy that is being pounced.
  events | The events that triggered the pounce.

## purple_pounce_get_data()

void* purple_pounce_get_data | ( | const PurplePounce * | pounce | ) |

Returns the pounce-specific data.

Parameters

  pounce | The buddy pounce.

Returns
  The data specific to a buddy pounce.

## purple_pounce_get_events()

PurplePounceEvent purple_pounce_get_events | ( | const PurplePounce * | pounce | ) |

Returns the events a pounce should watch for.

Parameters

  pounce | The buddy pounce.

Returns
  The events the pounce is watching for.

## purple_pounce_get_options()

PurplePounceOption purple_pounce_get_options | ( | const PurplePounce * | pounce | ) |

Returns the options for a pounce.

Parameters

  pounce | The buddy pounce.

Returns
  The options for the pounce.

## purple_pounce_get_pouncee()

const char* purple_pounce_get_pouncee | ( | const PurplePounce * | pounce | ) |

Returns the buddy a pounce should pounce on.

Parameters

  pounce | The buddy pounce.

Returns
  The buddy to pounce on.

## purple_pounce_get_pouncer()

PurpleAccount* purple_pounce_get_pouncer | ( | const PurplePounce * | pounce | ) |

Returns the account that will do the pouncing.

Parameters

  pounce | The buddy pounce.

Returns
  The account that will pounce.

## purple_pounce_get_save()

gboolean purple_pounce_get_save | ( | const PurplePounce * | pounce | ) |

Returns whether or not the pounce should save after execution.

Parameters

  pounce | The buddy pounce.

Returns
  `TRUE` if the pounce should be saved after execution, or `FALSE` otherwise.

## purple_pounce_new()

PurplePounce* purple_pounce_new | ( | const char * | ui_type,
|  | PurpleAccount * | pouncer,
|  | const char * | pouncee,
|  | PurplePounceEvent | event,
|  | PurplePounceOption | option
| ) |  |

Creates a new buddy pounce.

Parameters

  ui_type | The type of UI the pounce is for.
  pouncer | The account that will pounce.
  pouncee | The buddy to pounce on.
  event | The event(s) to pounce on.
  option | Pounce options.

Returns
  The new buddy pounce structure.

## purple_pounce_set_data()

void purple_pounce_set_data | ( | PurplePounce * | pounce,
|  | void * | data
| ) |  |

Sets the pounce-specific data.

Parameters

  pounce | The buddy pounce.
  data | Data specific to the pounce.

## purple_pounce_set_events()

void purple_pounce_set_events | ( | PurplePounce * | pounce,
|  | PurplePounceEvent | events
| ) |  |

Sets the events a pounce should watch for.

Parameters

  pounce | The buddy pounce.
  events | The events to watch for.

## purple_pounce_set_options()

void purple_pounce_set_options | ( | PurplePounce * | pounce,
|  | PurplePounceOption | options
| ) |  |

Sets the options for a pounce.

Parameters

  pounce | The buddy pounce.
  options | The options for the pounce.

## purple_pounce_set_pouncee()

void purple_pounce_set_pouncee | ( | PurplePounce * | pounce,
|  | const char * | pouncee
| ) |  |

Sets the buddy a pounce should pounce on.

Parameters

  pounce | The buddy pounce.
  pouncee | The buddy to pounce on.

## purple_pounce_set_pouncer()

void purple_pounce_set_pouncer | ( | PurplePounce * | pounce,
|  | PurpleAccount * | pouncer
| ) |  |

Sets the account that will do the pouncing.

Parameters

  pounce | The buddy pounce.
  pouncer | The account that will pounce.

## purple_pounce_set_save()

void purple_pounce_set_save | ( | PurplePounce * | pounce,
|  | gboolean | save
| ) |  |

Sets whether or not the pounce should be saved after execution.

Parameters

  pounce | The buddy pounce.
  save | `TRUE` if the pounce should be saved, or `FALSE` otherwise.

## purple_pounces_get_all()

GList* purple_pounces_get_all | ( | void |  | ) |

Returns a list of all registered buddy pounces.

Note
  The return value of this function must not be modified or freed.

Returns
  The list of buddy pounces.

## purple_pounces_get_all_for_ui()

GList* purple_pounces_get_all_for_ui | ( | const char * | ui | ) |

Returns a list of registered buddy pounces for the ui-type.

Parameters

  ui | The ID of the UI using the core.

Returns
  The list of buddy pounces. The list should be freed by the caller when it's no longer used.

Since
  2.1.0

## purple_pounces_get_handle()

void* purple_pounces_get_handle | ( | void |  | ) |

Returns the buddy pounce subsystem handle.

Returns
  The subsystem handle.

## purple_pounces_load()

gboolean purple_pounces_load | ( | void |  | ) |

Loads the pounces.

Returns
  `TRUE` if the pounces could be loaded.

## purple_pounces_register_handler()

void purple_pounces_register_handler | ( | const char * | ui,
|  | PurplePounceCb | cb,
|  | void(*)(PurplePounce *pounce) | new_pounce,
|  | void(*)(PurplePounce *pounce) | free_pounce
| ) |  |

Registers a pounce handler for a UI.

Parameters

  ui | The UI name.
  cb | The callback function.
  new_pounce | The function called when a pounce is created.
  free_pounce | The function called when a pounce is freed.

## purple_pounces_unregister_handler()

void purple_pounces_unregister_handler | ( | const char * | ui | ) |

Unregisters a pounce handle for a UI.

Parameters

  ui | The UI name.