profapi.h File Reference

Go to the source code of this file.

Typedefs
typedef char *	PROF_WIN_TAG
typedef void(*	CMD_CB) (char **args)
typedef void(*	TIMED_CB) (void)
typedef void(*	WINDOW_CB) (PROF_WIN_TAG win, char *line)

Functions
void	prof_cons_alert (void)
int	prof_cons_show (const char *const message)
int	prof_cons_show_themed (const char *const group, const char *const item, const char *const def, const char *const message)
int	prof_cons_bad_cmd_usage (const char *const cmd)
void	prof_register_command (const char *command_name, int min_args, int max_args, char **synopsis, const char *description, char *arguments[][2], char **examples, CMD_CB callback)
void	prof_register_timed (TIMED_CB callback, int interval_seconds)
void	prof_completer_add (const char *key, char **items)
void	prof_completer_remove (const char *key, char **items)
void	prof_completer_clear (const char *key)
void	prof_filepath_completer_add (const char *prefix)
void	prof_notify (const char *message, int timeout_ms, const char *category)
void	prof_send_line (char *line)
char *	prof_get_current_recipient (void)
char *	prof_get_current_muc (void)
int	prof_current_win_is_console (void)
char *	prof_get_current_nick (void)
char **	prof_get_current_occupants (void)
char *	prof_get_room_nick (const char *barejid)
void	prof_log_debug (const char *message)
void	prof_log_info (const char *message)
void	prof_log_warning (const char *message)
void	prof_log_error (const char *message)
void	prof_win_create (PROF_WIN_TAG win, WINDOW_CB input_handler)
int	prof_win_exists (PROF_WIN_TAG win)
int	prof_win_focus (PROF_WIN_TAG win)
int	prof_win_show (PROF_WIN_TAG win, char *message)
int	prof_win_show_themed (PROF_WIN_TAG tag, char *group, char *key, char *def, char *message)
int	prof_send_stanza (char *stanza)
int	prof_settings_boolean_get (char *group, char *key, int def)
void	prof_settings_boolean_set (char *group, char *key, int value)
char *	prof_settings_string_get (char *group, char *key, char *def)
void	prof_settings_string_set (char *group, char *key, char *value)
char **	prof_settings_string_list_get (char *group, char *key)
void	prof_settings_string_list_add (char *group, char *key, char *value)
int	prof_settings_string_list_remove (char *group, char *key, char *value)
int	prof_settings_string_list_clear (char *group, char *key)
int	prof_settings_int_get (char *group, char *key, int def)
void	prof_settings_int_set (char *group, char *key, int value)
void	prof_incoming_message (char *barejid, char *resource, char *message)
void	prof_disco_add_feature (char *feature)
void	prof_encryption_reset (char *barejid)
int	prof_chat_set_titlebar_enctext (char *barejid, char *enctext)
int	prof_chat_unset_titlebar_enctext (char *barejid)
int	prof_chat_set_incoming_char (char *barejid, char *ch)
int	prof_chat_unset_incoming_char (char *barejid)
int	prof_chat_set_outgoing_char (char *barejid, char *ch)
int	prof_chat_unset_outgoing_char (char *barejid)
int	prof_room_set_titlebar_enctext (char *roomjid, char *enctext)
int	prof_room_unset_titlebar_enctext (char *roomjid)
int	prof_room_set_message_char (char *roomjid, char *ch)
int	prof_room_unset_message_char (char *roomjid)
int	prof_chat_show (char *barejid, char *message)
int	prof_chat_show_themed (char *barejid, char *group, char *item, char *def, char *ch, char *message)
int	prof_room_show (char *roomjid, char *message)
int	prof_room_show_themed (char *roomjid, char *group, char *item, char *def, char *ch, char *message)

Detailed Description

C plugin API.

Typedef Documentation

typedef void(* CMD_CB) (char **args)

Type representing a function pointer to a command callback

typedef char* PROF_WIN_TAG

Type representing a window, used for referencing windows created by the plugin

typedef void(* TIMED_CB) (void)

Type representing a function pointer to a timed callback

typedef void(* WINDOW_CB) (PROF_WIN_TAG win, char *line)

Type representing a function pointer to a window callback

Function Documentation

int prof_chat_set_incoming_char	(	char *	barejid,
		char *	ch
	)

Set the incoming message prefix character for specified contact.

Parameters

barejid	Jabber ID of the recipient
ch	The character to display

Returns

1 on success, 0 on failure

int prof_chat_set_outgoing_char	(	char *	barejid,
		char *	ch
	)

Set the outgoing message prefix character for specified contact.

Parameters

barejid	Jabber ID of the recipient
ch	The character to display

Returns

1 on success, 0 on failure

int prof_chat_set_titlebar_enctext	(	char *	barejid,
		char *	enctext
	)

Set the text to display in the titlebar encryption indicator for recipient.

Parameters

barejid	Jabber ID of the recipient
enctext	The text to display

Returns

1 on success, 0 on failure

int prof_chat_show	(	char *	barejid,
		char *	message
	)

Show a message in a chat window.

Parameters

barejid	Jabber ID of the recipient
message	the message to print

Returns

1 on success, 0 on failure

int prof_chat_show_themed	(	char *	barejid,
		char *	group,
		char *	item,
		char *	def,
		char *	ch,
		char *	message
	)

Show a message in a chat window, using the specified theme, and prefix character Themes are specified in ~/.local/share/profanity/plugin_themes

Parameters

barejid	Jabber ID of the recipient
group	the group name in the themes file or NULL
item	the item name within the group or NULL
def	default colour if the theme cannot be found
ch	The character to prefix the message, or NULL for default behaviour
message	the message to print

Returns

1 on success, 0 on failure

int prof_chat_unset_incoming_char

(

char *

barejid

)

Reset the incoming message prefix character for specified contact.

Parameters

barejid

Jabber ID of the recipient

Returns

1 on success, 0 on failure

int prof_chat_unset_outgoing_char

(

char *

barejid

)

Reset the outgoing message prefix character for specified contact.

Parameters

barejid

Jabber ID of the recipient

Returns

1 on success, 0 on failure

int prof_chat_unset_titlebar_enctext

(

char *

barejid

)

Let profanity decide what to show in the titlebar encryption indicator for recipient.

Parameters

barejid

Jabber ID of the recipient

Returns

1 on success, 0 on failure

void prof_completer_add	(	const char *	key,
		char **	items
	)

Add values to be autocompleted by Profanity for a command, or command argument. If the key already exists, Profanity will add the items to the existing autocomplete items for that key.

Parameters

key	the prefix to trigger autocompletion
items	the items to return on autocompletion

void prof_completer_clear

(

const char *

key

)

Remove all values from autocompletion for a command, or command argument.

Parameters

key	the prefix from which to clear the autocompletion items

void prof_completer_remove	(	const char *	key,
		char **	items
	)

Remove values from autocompletion for a command, or command argument.

Parameters

key	the prefix from which to remove the autocompletion items
items	the items to remove

void prof_cons_alert

(

void

)

Highlights the console window in the status bar.

int prof_cons_bad_cmd_usage

(

const char *const

cmd

)

Show a message indicating the command has been called incorrectly.

Parameters

cmd	the command name with leading slash, e.g. "/say"

Returns

1 on success, 0 on failure

int prof_cons_show

(

const char *const

message

)

Show a message in the console window.

Parameters

message

the message to print

Returns

1 on success, 0 on failure

int prof_cons_show_themed	(	const char *const	group,
		const char *const	item,
		const char *const	def,
		const char *const	message
	)

Show a message in the console, using the specified theme. Themes are specified in ~/.local/share/profanity/plugin_themes

Parameters

group	the group name in the themes file
item	the item name within the group
def	default colour if the theme cannot be found
message	the message to print

Returns

1 on success, 0 on failure

int prof_current_win_is_console

(

void

)

Determine whether or not the Console window is currently focussed.

Returns

1 if the user is currently in the Console window, 0 otherwise.

void prof_disco_add_feature

(

char *

feature

)

Add a service discovery feature the list supported by Profanity. If a session is already connected, a presence update will be sent to allow any client/server caches to update their feature list for Profanity

Parameters

feature

the service discovery feature to be added

void prof_encryption_reset

(

char *

barejid

)

End any encrypted session with the specified user.

Parameters

barejid

Jabber ID of the recipient

void prof_filepath_completer_add

(

const char *

prefix

)

Add filepath autocompletion for a command, or command argument.

Parameters

prefix

the prefix from which filepath autocompletion will be triggered

char* prof_get_current_muc

(

void

)

Retrieve the Jabber ID of the current room, when in a chat room window.

Returns

the Jabber ID of the current chat room e.g. "metalchat@conference.chat.org", or NULL if not in a chat room window.

char* prof_get_current_nick

(

void

)

Retrieve the users nickname in a chat room, when in a chat room window.

Returns

the users nickname in the current chat room e.g. "eddie", or NULLL if not in a chat room window.

char** prof_get_current_occupants

(

void

)

Retrieve nicknames of all occupants in a chat room, when in a chat room window.

Returns

nicknames of all occupants in the current room or an empty list if not in a chat room window.

char* prof_get_current_recipient

(

void

)

Retrieve the Jabber ID of the current chat recipient, when in a chat window.

Returns

the Jabber ID of the current chat recipient e.g. "buddy@chat.org", or NULL if not in a chat window.

char* prof_get_room_nick

(

const char *

barejid

)

Retrieve current nickname used in chat room.

Parameters

barejid

The room's Jabber ID

Returns

Room nickname.

void prof_incoming_message	(	char *	barejid,
		char *	resource,
		char *	message
	)

Trigger incoming message handling, this plugin will make profanity act as if the message has been received

Parameters

barejid	Jabber ID of the sender of the message
resource	resource of the sender of the message
message	the message text

void prof_log_debug

(

const char *

message

)

Write to the Profanity log at level DEBUG.

Parameters

message

The message to log

void prof_log_error

(

const char *

message

)

Write to the Profanity log at level ERROR.

Parameters

message

The message to log

void prof_log_info

(

const char *

message

)

Write to the Profanity log at level INFO.

Parameters

message

The message to log

void prof_log_warning

(

const char *

message

)

Write to the Profanity log at level WARNING.

Parameters

message

The message to log

void prof_notify	(	const char *	message,
		int	timeout_ms,
		const char *	category
	)

Send a desktop notification.

Parameters

message	the message to display in the notification
timeout_ms	the length of time before the notification disappears in milliseconds
category	the category of the notification, also displayed

void prof_register_command	(	const char *	command_name,
		int	min_args,
		int	max_args,
		char **	synopsis,
		const char *	description,
		char *	arguments[][2],
		char **	examples,
		CMD_CB	callback
	)

Register a new command, with help information, and callback for command execution. Profanity will do some basic validation when the command is called using the argument range.

Parameters

command_name	the command name with leading slash, e.g. "/say"
min_args	minimum number or arguments that the command considers to be a valid call
max_args	maximum number or arguments that the command considers to be a valid call
synopsis	command usages
description	a short description of the command
arguments	argument descriptions
examples	example usages
callback	The CMD_CB function to execute when the command is invoked

void prof_register_timed	(	TIMED_CB	callback,
		int	interval_seconds
	)

Register a function that Profanity will call periodically.

Parameters

callback	The TIMED_CB function to execute
interval_seconds	the time between each call to the function, in seconds

int prof_room_set_message_char	(	char *	roomjid,
		char *	ch
	)

Set the message prefix character for specified room.

Parameters

roomjid	Jabber ID of the room
ch	The character to display

Returns

1 on success, 0 on failure

int prof_room_set_titlebar_enctext	(	char *	roomjid,
		char *	enctext
	)

Set the text to display in the titlebar encryption indicator for room.

Parameters

roomjid	Jabber ID of the room
enctext	The text to display

Returns

1 on success, 0 on failure

int prof_room_show	(	char *	roomjid,
		char *	message
	)

Show a message in a chat room window.

Parameters

barejid	Jabber ID of the room
message	the message to print

Returns

1 on success, 0 on failure

int prof_room_show_themed	(	char *	roomjid,
		char *	group,
		char *	item,
		char *	def,
		char *	ch,
		char *	message
	)

Show a message in a chat room window, using the specified theme, and prefix character Themes are specified in ~/.local/share/profanity/plugin_themes

Parameters

barejid	Jabber ID of the room
group	the group name in the themes file or NULL
item	the item name within the group or NULL
def	default colour if the theme cannot be found
ch	The character to prefix the message, or NULL for default behaviour
message	the message to print

Returns

1 on success, 0 on failure

int prof_room_unset_message_char

(

char *

roomjid

)

Reset the message prefix character for specified room.

Parameters

roomjid

Jabber ID of the room

Returns

1 on success, 0 on failure

int prof_room_unset_titlebar_enctext

(

char *

roomjid

)

Let profanity decide what to show in the titlebar encryption indicator for room.

Parameters

roomjid

Jabber ID of the room

Returns

1 on success, 0 on failure

void prof_send_line

(

char *

line

)

Send a line of input to Profanity to execute.

Parameters

line	the line to send

int prof_send_stanza

(

char *

stanza

)

Send an XMPP stanza

Parameters

stanza

an XMPP stanza

Returns

1 if the stanza was sent successfully, 0 otherwise

int prof_settings_boolean_get	(	char *	group,
		char *	key,
		int	def
	)

Get a boolean setting Settings must be specified in ~/.local/share/profanity/plugin_settings

Parameters

group	the group name in the settings file
key	the item name within the group
def	default value if setting not found

Returns

the setting, or default value

void prof_settings_boolean_set	(	char *	group,
		char *	key,
		int	value
	)

Set a boolean setting Settings must be specified in ~/.local/share/profanity/plugin_settings

Parameters

group	the group name in the settings file
key	the item name within the group
value	value to set

int prof_settings_int_get	(	char *	group,
		char *	key,
		int	def
	)

Get an integer setting Settings must be specified in ~/.local/share/profanity/plugin_settings

Parameters

group	the group name in the settings file
key	the item name within the group
def	default value if setting not found

Returns

the setting, or default value

void prof_settings_int_set	(	char *	group,
		char *	key,
		int	value
	)

Set an integer setting Settings must be specified in ~/.local/share/profanity/plugin_settings

Parameters

group	the group name in the settings file
key	the item name within the group
value	value to set

char* prof_settings_string_get	(	char *	group,
		char *	key,
		char *	def
	)

Get a string setting Settings must be specified in ~/.local/share/profanity/plugin_settings

Parameters

group	the group name in the settings file
key	the item name within the group
def	default value if setting not found

Returns

the setting, or default value

void prof_settings_string_list_add	(	char *	group,
		char *	key,
		char *	value
	)

Add an item to a string list setting Settings must be specified in ~/.local/share/profanity/plugin_settings If the list does not exist, a new one will be created with the element added

Parameters

group	the group name in the settings file
key	the item name within the group
value	item to add

int prof_settings_string_list_clear	(	char *	group,
		char *	key
	)

Remove all items from a string list setting Settings must be specified in ~/.local/share/profanity/plugin_settings

Parameters

group	the group name in the settings file
key	the item name within the group

Returns

1 if the list was cleared, 0 if the list does not exist

char** prof_settings_string_list_get	(	char *	group,
		char *	key
	)

Get a string list setting Settings must be specified in ~/.local/share/profanity/plugin_settings The string list setting items are separated by semicolons.

Parameters

group	the group name in the settings file
key	the item name within the group

Returns

the list setting

int prof_settings_string_list_remove	(	char *	group,
		char *	key,
		char *	value
	)

Remove an item from a string list setting Settings must be specified in ~/.local/share/profanity/plugin_settings

Parameters

group	the group name in the settings file
key	the item name within the group
value	item to remove

Returns

1 if the item was removed, or is not in the list, 0 if the list does not exist

void prof_settings_string_set	(	char *	group,
		char *	key,
		char *	value
	)

Set a string setting Settings must be specified in ~/.local/share/profanity/plugin_settings

Parameters

group	the group name in the settings file
key	the item name within the group
value	value to set

void prof_win_create	(	PROF_WIN_TAG	win,
		WINDOW_CB	input_handler
	)

Create a plugin window.

Parameters

win	The PROF_WIN_TAG used to refer to the window
input_handler	The WINDOW_CB function to call when the window receives input

int prof_win_exists

(

PROF_WIN_TAG

win

)

Determine whether or not a plugin window currently exists for PROF_WIN_TAG.

Parameters

win	the PROF_WIN_TAG used when creating the plugin window

Returns

1 if the window exists, 0 otherwise

int prof_win_focus

(

PROF_WIN_TAG

win

)

Focus plugin window.

Parameters

win	the PROF_WIN_TAG of the window to focus

Returns

1 on success, 0 on failure

int prof_win_show	(	PROF_WIN_TAG	win,
		char *	message
	)

Show a message in the plugin window.

Parameters

win	the PROF_WIN_TAG of the window to display the message
message	The message to print

Returns

1 on success, 0 on failure

int prof_win_show_themed	(	PROF_WIN_TAG	tag,
		char *	group,
		char *	key,
		char *	def,
		char *	message
	)

Show a message in the plugin window, using the specified theme. Themes are specified in ~/.local/share/profanity/plugin_themes

Parameters

tag	The PROF_WIN_TAG of the window to display the message
group	the group name in the themes file
key	the item name within the group
def	default colour if the theme cannot be found or NULL
message	the message to print

Returns

1 on success, 0 on failure