Module programming interface

Overview

TODO

The Temple Public Interface (TPI)

The TPI is the lowest-level C interface to the Temple plug-in architecture. It provides a series of functions to manipulate data (such as calcs) and to handle events.

SQL Interface

tpi_sql_register_interface

• Prototype:

  int    tpi_sql_register_interface (
  		char const *            interface_name,		[in]
  		char const *            interface_description,	[in]
  		tpi_sql_fn_connect      connect_fn,		[in]
  		tpi_sql_fn_disconnect   disconnect_fn,		[in]
  		tpi_sql_fn_query        query_fn,		[in]
  		tpi_sql_fn_cmd          cmd_fn,			[in]
  		tpi_sql_fn_commit       commit_fn,		[in]
  		tpi_sql_fn_rollback     rollback_fn,		[in]
  		tpi_sql_fn_err          err_fn			[in]
  	);
  

• Preconditions: interface_name and interface_description point to NUL-terminated arrays of char. All other functions point to functions of the required type.

• Postconditions: None

• Side effects: A new SQL interface is registered with the database subsystem.

• Return values:
  • 1: Successful completion.
  • 0: An error occured and the new interface was not registered.

DCO Interface

A DCO represents an object in Temple's database, such as a user or a calc. Every DCO has a type, such as "user" or "calc", a name, such as "larne", and a series of attribute/value pairs.
The basic type for dealing with DCO objects with TPI is the tpi_dco_ctx, an opaque type representing a handle to a single DCO object. To obtain a handle to a new DCO object, call tpi_dco_new(); when the object is finished with, destroy it with tpi_dco_delete(). Attributes of DCOs may be retrieved with the tpi_dco_get_attr() function.

Example

	/* Retrieve and print the "text" attribute of the "calc" DCO "test". */
	tpi_dco_ctx c;
	char *text;
	
	if (tpi_dco_new(&c, "calc", "test") == 0)
		return 1; /* error */
	
	if (tpi_dco_get_attr(c, "text", &text) == 0) {
		tpi_dco_delete(c);
		return 1; /* error */
	}

	print("text is [%s]\n", text);
	free(text);
	tpi_dco_delete(c);

tpi_dco_new

• Prototype:

  int    tpi_dco_new (
  		tpi_dco_ctx *	ctx,	[out]
  		char const *	type, 	[in]
  		char const *	name	[in]
  	);
  

• Preconditions: type and name point to NUL-terminated arrays of char.

• Postconditions: ctx is initialised to point to a new DCO object, with name as type as described by name and type.

• Side effects: None.

• Return values:
  • 1: Successful completion.
  • 0: An error occured. The contents of ctx are indeterminate.

• Notes: The value stored in ctx must be destroyed when it is no longer required by a call to tpi_dco_delete.

tpi_dco_delete

• Prototype:

  int tpi_dco_delete (
  		tpi_dco_ctx 	ctx,	[in]
  	);
  

• Preconditions: ctx points to a valid DCO object.

• Postconditions: The DCO object is destroyed and any associated resources are freed. The DCO data is not removed from the database.

• Side effects: None.

• Return values:
  • 1: Successful completion.

tpi_dco_exists

• Prototype:

  int tpi_dco_exists (
  		tpi_dco_ctx 	ctx	[in]
  	);
  

• Preconditions: ctx points to a valid DCO object.

• Postconditions: None.

• Side effects: None.

• Return values:
  • 0: The DCO object does not exist in the database.
  • 1: The DCO object does exist in the database.

tpi_dco_create

• Prototype:

  int tpi_dco_create (
  		tpi_dco_ctx 	ctx	[in]
  	);
  

• Preconditions: ctx is a valid DCO object.

• Postconditions: None.

• Side effects: The DCO object described by ctx is created in the database.

• Return values:
  • 1: Successful completion.
  • 0: An error occured. The DCO object was not created.

tpi_dco_has_attr

• Prototype:

  int tpi_dco_has_attr (
  		tpi_dco_ctx 	ctx,	[in]
  		char const *	attr	[in]
  	);
  

• Preconditions: ctx is a valid DCO object. attr points to a NUL-terminated array of char.

• Postconditions: None.

• Side effects: None.

• Return values:
  • 1: The DCO object ctx contains the attribute with the name specified by attr.
  • 0: The DCO object does not contain this attribute.

tpi_dco_get_attr

• Prototype:

  int tpi_dco_get_attr (
  		tpi_dco_ctx 	ctx,		[in]
  		char const *	attr_name,	[in]
  		char **		attr_value	[out]
  	);
  

• Preconditions: ctx is a valid DCO object. attr_name points to a NUL-terminated array of char.

• Postconditions: attr_value is initialised to point to a NUL-terminated array of char which contains the value of the attr_name attribute.

• Side effects: None.

• Return values:
  • 1: Successful completion.
  • 0: An error occured. The contents of attr_value are indeterminate.

• Notes: The pointer stored in attr_value must be freed by a call to free() when it is no longer required.

tpi_dco_set_attr

• Prototype:

  int tpi_dco_set_attr (
  		tpi_dco_ctx 	ctx,		[in]
  		char const *	attr_name,	[in]
  		char const *	new_value	[in]
  	);
  

• Preconditions: ctx is a valid DCO object which exists in the dabtase. attr_name and attr_value point to NUL-terminated arrays of char.

• Postconditions: None.

• Side effects: The value of the attribute attr_name of the DCO object ctx is changed to new_value. If this attribute does not exist, it is created.

• Return values:
  • 1: Successful completion.
  • 0: An error occured. The value of the attribute was not changed.

tpi_dco_del_attr

• Prototype:

  int tpi_dco_del_attr (
  		tpi_dco_ctx 	ctx,		[in]
  		char const *	attr_name	[in]
  	);
  

• Preconditions: ctx is a valid DCO object. attr_name is a pointer to a NUL-terminated array of char.

• Postconditions: None.

• Side effects: The attribute attr_name is removed from the DCO object ctx.

• Return values:
  • 1: Successful completion.
  • 0: An error occured. The attribute was not removed.

tpi_dco_name

• Prototype:

  char const *tpi_dco_name (
  		tpi_dco_ctx	ctx	[in]
  	);
  

• Preconditions: ctx is a valid DCO object.

• Postconditions: None.

• Side effects: None.

• Return values: A pointer to NUL-terminated array of char is returned, which contains the name of the DCO object ctx.

tpi_dco_find_by_key

• Prototype:

  int tpi_dco_find_by_key (
  		char const *			type,		[in]
  		char const *			pattern,	[in]
  		tpi_dco_ctx [out] * [out] *	results,
  		int *				nmatches	[out]
  	);
  

• Preconditions: type and pattern point to NUL-terminated arrays of char.

• Postconditions: results points to an array of tpi_dco_ctxs of type type whose name matches the pattern pattern. nmatches contains the number of objects in the array.

• Side effects: None.

• Return values:
  • 1: Successful completion.
  • 0: An error occured. The contains of results and nmatches are indeterminate.

• Notes: Every element of the array results must be freed by a call to tpi_dco_delete() when it is no longer required. The array itself must be freed by a call to free().

tpi_dco_find_by_attr

• Prototype:

  int tpi_dco_find_by_attr (
  		char const *			type,		[in]
  		char const *			attr,		[in]
  		char const *			pattern,	[in]
  		tpi_dco_ctx [out] * [out] *	results,
  		int *nmatches					[out]
  	);
  

• Preconditions: type, attr and pattern are pointers to NUL-terminated arrays of char.

• Postconditions: results is a pointer to an array of tpi_dco_ctx objects of type type, whose attribute specified by attr matches the pattern pattern. nmatches contains the size of this array.

• Return values:
  • 1: Successful completion.
  • 0: An error occured. The contents of results and nmatches is indeterminate.

• Notes: Every element of the array results must be freed by a call to tpi_dco_delete() when it is no longer required. The array itself must be freed by a call to free().

tpi_dco_get_stats

• Prototype:

  int tpi_get_get_stats (
  		char const *	type,	[in]
  		int *		nobjs	[out]
  	);
  

• Preconditions: type is a pointer to a NUL-terminated array of char.

• Postconditions: nobjs contains the number of DCO objects in the database of type type.

• Side effects: None.

• Return values:
  • 1: Successful completion.
  • 0: An error occured. The contents of nobjs is indeterminate.

tpi_dco_get_error

• Prototype:

  char const *tpi_get_get_error (
  		tpi_dco_ctx	ctx	[in]
  	);
  

• Preconditions: ctx is a valid DCO object.

• Postconditions: None.

• Side effects: None.

• Return values: A pointer to a NUL-terminated array of char describing the last error condition related to the DCO object ctx, or NULL if no error condition has occured.

Server connection functions

tpi_serv_reply_any

• Prototype:

  int tpi_serv_reply_any (
  		tpi_serv_reply_ctx	repl_ctx,	[in]
  		char const *		message,	[in]
  		...					[in]
  	);
  

• Preconditions: repl_ctx is a valid server reply context. message points to a NUL-terminated array of char. The optional extra arguments list contains any number of pointers to NUL-terminated arrays of char, terminated with a NULL pointer.

• Postconditions: None.

• Side effects: The string message is looked up in the message catalogue. Its arguments are replaced sequentially by the optional arguments. The resulting text is then sent to the user. If the the reply context indicates the the original message was received as a public channel message, the reply is sent in the channel, prefixed by the nickname of the user; if the command was received via a private message, the message is sent via a private message.

• Return values:
  • 1: Successful completion.
  • 0: An error occured. The message was not delivered.

tpi_serv_reply_private

• Prototype:

  int tpi_serv_reply_private (
  		tpi_serv_repl_ctx	repl_ctx,	[in]
  		char const *		message,	[in]
  		...					[in]
  	);
  

tpi_serv_send_message

• Prototype:

  int tpi_serv_send_message (
  		tpi_serv_ctx 	ctx,		[in]
  		char const *	target,		[in]
  		char const *	message,	[in]
  		...				[in]
  	);
  

• Preconditions: ctx is a valid server context. target and message are pointers to nul-terminated arrays of char. The optional extra arguments are pointers to nul-terminated arrays of char, terminated by a NULL pointer.

• Postconditions: None.

• Side effects: The message message is looked up in the message catalogue. Its arguments are replaced sequentially by the optional arguments. The resulting text is then sent to target, which may be a nickname or a channel name.

• Return values:
  • 1: Successful completion.
  • 0: An error occured. The message was not delivered.

tpi_serv_repl_from_nick

• Prototype:

  char const *tpi_serv_repl_from_nick (
  		tpi_serv_reply_ctx 	repl_ctx	[in]
  	);
  

tpi_serv_repl_new

• Prototype:

  int tpi_serv_repl_new (
  		tpi_serv_repl_ctx *	ctx,		[out]
  		tpi_serv_ctx 		serv_ctx	[in]
  	);
  

• Preconditions: serv_ctx is a valid server context.

• Postconditions: ctx contains a new reply context associated with the server serv_ctx.

• Side effects: None.

• Return values:
  • 1: Successful completion.
  • 0: An error occured. The contents of ctx are indeterminate.

• Notes: The reply context must be destroyed via a call to tpi_serv_repl_delete() when it is no longer required.

tpi_serv_set_from_nick

• Prototype:

  int tpi_serv_repl_set_from_nick (
  		tpi_serv_repl_ctx repl_ctx,	[in]
  		char const *nick		[in]
  	);
  

• Preconditions: repl_ctx is a valid reply context. nick is a pointer to nul-terminated array of char.

• Postconditions: None.

• Side effects: The nickname associated with the reply context repl_ctx is changed to nick.

• Return values:
  • 1: Successful completion.
  • 0: An error occured. The nickname associated with the reply context was not changed.

tpi_serv_set_target

• Prototype:

  int tpi_serv_repl_set_target (
  		tpi_serv_repl_ctx 	repl_ctx,	[in]
  		char const *		target		[in]
  	);
  

• Preconditions: repl_ctx is a valid reply context. target is a pointer to a nul-terminated array of characters.

• Postconditions: None.

• Side effects: The target associated with the reply context repl_ctx is changed to target.

• Return values:
  • 1: Successful completion.
  • 0: An error occured. The target associated with the context was not changed.

tpi_serv_repl_set_private

• Prototype:

  int tpi_serv_repl_set_private (
  		tpi_serv_repl_ctx 	repl_ctx,	[in]
  		int 			priv		[in]
  	);
  

• Preconditions: repl_ctx is a valid server reply context. priv is an integer of value 0 or 1.

• Postconditions: None.

• Side effects: If priv is 0, the reply context is changed to a non-private (public channel) reply context. If priv is 1, the reply context is changed to a private context.

• Return values:
  • 1: Successful completion.
  • 0: An error occured. The reply context was not changed.

tpi_serv_join_channel

• Prototype:

  int tpi_serv_join_channel (
  		tpi_serv_ctx 	ctx,	[in]
  		char const *	channel	[in]
  	);
  

• Preconditions: ctx is a valid server context. channel is a pointer to a nul-terminated array of char.

• Postconditions: None.

• Side effects: A JOIN command for the channel specified in channel is sent to the server ctx. The channel may not actually be joined if the server rejects the JOIN command.

• Return values:
  • 1: Successful completion.
  • 0: An error occured. The JOIN channel was not sent to the server.

tpi_serv_send_raw

• Prototype:

  int tpi_serv_send_raw (
  		tpi_serv_ctx 	ctx,	[in]
  		char const *	text	[in]
  	);
  

tpi_serv_add_user_to_channel

• Prototype:

  int tpi_serv_add_user_to_channel (
  			tpi_serv_ctx 	ctx,	[in]
  			char const *	user,	[in]
  			chat const *	channel	[in]
  		);
  

tpi_serv_remove_user_from_channel

• Prototype:

  int tpi_serv_change_user_nickname (	
  			tpi_serv_ctx 	ctx,	[in]
  			char const *	user,	[in]
  			chat const *	newnick	[in]
  		);
  

tpi_serv_signoff_user

• Prototype:

  int tpi_serv_signoff_user (
  		tpi_serv_ctx 	ctx,	[in]
  		char const *	user	[in]
  	);
  

Event functions

tpi_event_install_handler

• Prototype:

  void tpi_event_install_handler (
  		char const *		event,	[in]
  		tpi_event_callback_fn 	fb	[in]
  	);
  

tpi_event_raise

• Prototype:

  void tpi_event_raise (
  		char const *event,	[in]
  		char const *data	[in]
  	);
  

User functions

tpi_user_has_priv

• Prototype:

  int tpi_user_has_priv (
  		tpi_user_ctx user,	[in]
  		char const *priv	[in]
  	);
  

tpi_user_name

• Prototype:

  char const * tpi_user_name (
  		tpi_user_ctx 	user	[in]
  	);
  

tpi_user_find

• Prototype:

  int tpi_user_find (
  		tpi_user_ctx *	user,		[out]
  		char const *	username	[in]
  	);
  

tpi_user_find_by_host

• Prototype:

  int tpi_user_find_by_host (
  		tpi_user_ctx *	user,		[out]
  		char const *	hostname	[in]
  	);
  

tpi_user_delete

• Prototype:

  int tpi_user_delete (
  		tpi_user_ctx 	user	[in]
  	);
  

Configuration functions

tpi_conf_get_list

• Prototype:

  int tpi_conf_get_list (
  		char const *			value,		[in]
  		char [out] * [out] * [out] *	result,	
  		int *				nresults	[out]
  	);
  

Miscellaneous functions

tpi_log_message

• Prototype:

  int tpi_log_message (
  		char const *category,	[in]
  		char const *severity,	[in]
  		char const *message	[in]
  	);