The AKT-Bus API for Prolog
==========================

Message Composition
-------------------

Predicate:	compose_message/4
		compose_message(+Sender,+Receiver,+Content,-Message)

Desc:		Compose a message, system will fill in date & time stamps.
		If "Content" is not a term structure, a simple message is assumed.

Params:		+Sender		=	Sender's URI as an atom or a string.
					If sender URI is the empty list "[]" or the atom "null",
					then no sender URI will be put in.
					Empty sender should only be used when expecting a piggy-packed reply.
		+Receiver	=	Receiver's URI as an atom or a string.
					If receiver URI is the empty list "[]" or the atom "null",
					then no receiver URI will be put in.
					Empty receiver should only be used when sending a piggy-packed reply.
		+Content	=	Content to be put into message.
					If content is an atom, then a "aktbus:SimpleContent" is added.
		-Message	=	The composed message.


Predicate:	compose_message/5
		compose_message(+Sender,+Receiver,+Content,+Name_spaces,-Message)

Desc:		Similar to compose_message/4.
		Except that user can specify extra name space definitions in a list.

Params:		+Sender		=	Sender's URI as an atom or a string.
		+Receiver	=	Receiver's URI as an atom or a string.
		+Content	=	Content to be put into message.
		+Name_spaces	=	A list of extra name space definitions in the form X=Y.
		-Message	=	The composed message.


Message Decomposition
---------------------
Predicate:	decompose_message/8
		decompose_message(-Sender,-Receiver,-Date,-Time,-Msg_id,+Content,-Extra,+Message)

Desc:		Decompose messagse into components.

Params:		-Sender		=	Sender of message as an atom.
					Return "[]" if no sender is specified.
		-Receiver	=	Receiver of message as an atom.
					Return "[]" if no receiver is specified.
		-Date		=	Date stamp.
		-Time		=	Time stamp.
		-Msg_id		=	Message id.
		-Content	=	Content of message.
		-Extra		=	Extra name space definitions in a list.
		+Message	=	The message to decompose.


Predicate:	get_receiver_uri/2
		get_receiver_uri(+Message,-Uri)

Desc:		Get URI of receiver from a message.

Params:		+Message	=	Message.
		-Uri		=	URI of the receiver.
					Return "[]" if no receiver URI is found.

Predicate:	parse_url/2
		parse_url(-Url_term,+Url)

Desc:		Parse a URL into a url/3 term.

Params:		-Url_term	=	The parsed URL as a url/3 term.
		+Url		=	The URL to parsed. Either an atom or a string.


Predicate:	string_to_xml/2
		string_to_xml(?String,?Xml)

Desc:		Parse a string into a XML tree or convert a XML tree into a string.

Params:		?String		=	A string to parse or generated.
		?Xml		=	Prolog term structures describing an XML tree.


Predicate:	get_env/4
		get_env(+Tree,+Env,-Attrib,-Value)

Desc:		Given a tag name, extract its attributes & value from an XML tree.

Params:		+Tree	=	The XML tree to search.
		+Env	=	The tag/environment name to search for.
		-Attrib	=	The returns attribute list.
		-Value	=	The enironment value.


Message Sending
---------------
Predicate:	close_connection/1
		close_connection(+Connection)

Desc:		Close a connection.

Params:		+Connection	=	The network connection to close.


Predicate:	send_message/1
		send_message(+Message)

Desc:		Send a message to its default receiver.
		Expect no piggy-packed reply.

Params:		+Message	=	The message to send.


Predicate:	send_message/3
		send_message(+Message,+Somewhere,+Timeout)

Desc:		Send message to somewhere, specifying timeout value.

Params:		+Message	=	The message to send.
		+Somewhere	=	The destination, overridding the one in receiver URI.
					This can be a URL (in atom/string), or a connection.
					A connection is only used to send piggy-packed reply.
		+Timeout	=	The timeout value in a time/2 format.
					i.e. second & micro-second.

Predicate:	send_and_receive/4
		send_and_receive(+Message,+Somewhere,+Timeout,-Reply)

Desc:		Send message to somewhere, specifying timeout value
		and receive the piggy-packed reply.
Params:		+Message	=	The message to send.
		+Somewhere	=	The destination, overidding the one in the receiver URI.
					This can be the atom "default", meaning the default receiver.
					Or a URL (in atom/string).

Message Receiving
-----------------
Predicate:	create_aktbus_receiver/2
		create_aktbus_receiver(+Something,-Receiver)

Desc:		Create an AKT-Bus receiver listening to a certain port.

Params:		+Something	=	"Something" can be a port number (i.e. an integer).
					Or a URL, which is either an atom or a string.
		-Receiver	=	The created AKT-Bus receiver.


Predicate:	destroy_aktbus_receiver/1
		destroy_aktbus_receiver(+Receiver)

Desc:		Destroying an AKT-Bus receiver.

Params:		+Receiver	=	The receiver to destroy.


Predicate:	receive_message/2
		receive_message(+Receiver,-Message)

Desc:		Receive a message from somewhere.

Params:		+Receiver	=	An AKT-Bus receiver created by create_aktbus_receiver/2.
					The connection is closed after receiving.
		-Message	=	The received message.


Predicate:	receive_message/3
		receive_message(+Receiver,-Message,-Connection)

Desc:		Receive a message from an AKT-Bus receiver, retaining connection.

Params:		+Receiver	=	An AKT-Bus receiver created by create_aktbus_receiver/2.
					The connection is kept after receiving.
					To close it, use close_connection/1.
		-Message	=	The received message.
		-Connection	=	The network connection for sending a piggy-packed reply.

Miscellaneous
-------------
Predicate:	print_string/1
		print_string(+String)

Desc:		Print a string to stdout.

Params:		+String	=	The string to print in a list.

Predicate:	print_string/2
		print_string(+String,+Stream)

Desc:		Print a string to a stream.

Params:		+String	=	The string to print in a list.
		+Stream	=	The output stream to print the string.