From Pidgin Games

[edit] Game Plugin API Reference

This API contains every communication between game plugins and the game support plugin. It is realized with the libpurple's IPC which unfortunately is still undocumented.

Green methods will be send from your plugin to the game support plugin. Orange methods will be emitted by the game support which means that you have to provide them. Have a look at the test game plugin to see how that works.

[edit] Registering

[edit] game-register

void (*game_register)(char *game_id, PurplePlugin *plugin, char *name);

Description: Emitted when your plugin wants to register a game. On Emitting game support will register all orange signals for the game with your plugin as recipient.
Parameters: game_id The namespace of the game; plugin The purple plugin handle; name The game's human-readable name

[edit] game-unregister

void (*game_unregister)(char *game_id);

Description: Emitted when your plugin wants to unregister a game, e.g. on unloading or if user disabled the game in a multi-game plugin.
Parameters: game_id The namespace of the game

[edit] Match

[edit] match-create

void (*create_match)(char *match_id, gboolean initiator, char *options, char *alias);

Description: Emitted when a new game was created. On receiving your plugin should present the game UI to the user.
Parameters: match_id The unique id of the match; initiator Wether the client is the initiator or the invitee; options The supplied options as an XML string; alias The human-readable name of the opponent

[edit] match-send-turn

void (*match_send_turn)(char *match_id, char *turn);

Description: Emitted when you want to send a turn to an opponent for the given match.
Parameters: match_id The unique id of the match; turn The turn you make as an XML string (i.e. everything inside the <turn/> tag)

[edit] match-send-term

void (*match_send_term)(char *match_id, char *reason);

Description: Emitted when you want to end the given match.
Parameters: match_id The unique id of the match; reason The reason you terminated the match for (see [1] for possible values]

[edit] match-send-renew

void (*match_send_renew)(char *match_id, char *options);

Description: Emitted when you want to renew a terminated match.
Parameters: match_id The unique id of the original match.; options The options of the new match as defined by the game specification.

[edit] match-received-turn

void (*match_received_turn)(char *match_id, char *turn);

Description: Emitted when game support receives a turn message for an active match associated with your plugin.
Parameters: match_id The unique id of the match; turn Your opponents turn as an XML string

[edit] match-received-term

void (*match_received_term)(char *match_id, char *reason);

Description: Emitted when game support receives a terminate message for an active match associated with your plugin.
Parameters: match_id The unique id of the match; reason The reason your opponent terminated the match for

[edit] Options

[edit] options-get

void (*get_options)(char **options);

Description: Emitted when game support wants to use the current options for an invitation.
Parameters: options The current options as set by the user or default options as an XML string

[edit] options-set

void (*set_options)(void);

Description: Emitted when game support wants to enable the user to set the options. It is up to the game plugin to save the chosen options.
Parameters: none

[edit] options-parse

gboolean (*parse_options)(char *options, char **opts_str, gboolean *details);

Description: Emitted when the game support plugin receives an invitation and needs to validate the options.
Return Value: Whether the options are valid or not
Parameters: options The options to check as an XML string; opts_str A short description of the options supplied. Must not be longer than a few sentences.; details Whether the options are not fully described in opts_str. If this is the case, Game Support will display a "Details" button.

[edit] options-show

void (*show_options)(char *options);

Description: Emitted when game support wants to present the detailed options to the user (i.e. when the user presses the "Details" button)
Parameters: options The options to show as an XML string

[edit] Saving / Loading

[edit] state-show

void (*show_state)(char *state, char *options);

Description: Similar to options-show but emitted when game support wants to present the details of an invitation to an adjourned match
Parameters: state The state as an XML string; options The match options as an XML string

[edit] match-received-save

gboolean (*received_save)(char *match_id, char *state);

Description: Emitted when game support wants to signal that the opponent issued a saving process.
Return Value: Whether the match should be saved on your side too - Necessary for mutual saves.
Parameters: match_id The unique id of the match; state The state as an XML string

[edit] match-load

void (*load_match)(char *match_id, char *state, char *options, char *alias);

Description: Similar to match-create but emitted when an adjourned game was loaded. On receiving your plugin should present the game UI to the user.
Parameters: match_id The unique id of the match; state The state as an XML string; options The supplied options as an XML string; alias The human-readable name of the opponent

[edit] match-save

void (*match_send_save)(char *match_id, gboolean is_mutual, char *state);

Description: Emitted when you want to save the match.
Parameters: match_id The unique id of the match; is_mutual Whether the match has to be saved by both parties; state The state as an XML string

GamePluginAPI