<!-- Module Developer's Guide -->

<chapter>
	<title>&develguide;</title>
	<para>
		The module provides an API that can be used from other
		&osips; modules. The API offers the functions for creating and handing dialogs.
		A dialog can be created on a receipt initial message, and this will correspond to
		a b2b server entity, or initiated by the server and in this case a client entity
		will be created in b2b_entities module.
	</para>
		<section>
				<title>
				<function moreinfo="none">b2b_load_api(b2b_api_t* api)</function>
				</title>
			<para>
				This function binds the b2b_entities modules and fills the structure 
				the exported functions that will be described in detail.
			</para>
		<example>
		<title><function>b2b_api_t</function> structure</title>
	<programlisting format="linespecific">
...
typedef struct b2b_api {
	b2b_server_new_t          server_new;
	b2b_client_new_t          client_new;

	b2b_send_request_t        send_request;
	b2b_send_reply_t          send_reply;

	b2b_entity_delete_t       entity_delete;

	b2b_restore_linfo_t       restore_logic_info;
	b2b_update_b2bl_param_t   update_b2bl_param;
}b2b_api_t;
...
</programlisting>
		</example>

		</section>
	
	<section>
		<title>
		<function moreinfo="none">server_new</function>
		</title>
		<para>
			Field type:
		</para>
			<programlisting format="linespecific">
...
typedef str* (*b2b_server_new_t) (struct sip_msg* , str* local_contact,
		b2b_notify_t , str *mod_name, str* logic_key, struct b2b_tracer *tracer,
		void *param, b2b_param_free_cb free_param);
...
</programlisting>
		<para>
			This function asks the b2b_entities modules to create a new server 
			entity record. The internal processing actually extracts the dialog information
			from the message and constructs a record that will be stored in a hash table.
			The second parameters is a pointer to a function that the b2b_entities module
			will call when a event will come for that dialog (a request or reply). The third
			parameter is a pointer to a value that will be stored and given as a parameter
			when the notify function will be called(it has to be allocated in shared memory).
		</para>
		<para>
			The return value is an identifier for the record that will be mentioned when 
			calling other functions that represent actions in the dialog(send request,
			send reply).
		</para>
		<para>
		The notify function has the following prototype:
		</para>
	<programlisting format="linespecific">
...
typedef int (*b2b_notify_t)(struct sip_msg* msg, str* id, int type, void* param);
...
</programlisting>
	<para>
		This function is called when a request or reply is received for a dialog 
		handled by b2b_entities. The first parameter is the message, the second is the
		identifier for the dialog, the third is a flag that says which is the type of
		the message(it has two possible values - B2B_REQUEST and B2B_REPLY). The last
		parameter is the parameter by the upper module when the entity was created.
	</para>
</section>

<section>
		<title>
		<function moreinfo="none">client_new</function>
		</title>
		<para>
			Field type:
		</para>
			<programlisting format="linespecific">
...
typedef str* (*b2b_client_new_t) (client_info_t* , b2b_notify_t b2b_cback,
				b2b_add_dlginfo_t add_dlginfo_f, str *mod_name, str *logic_key,
				struct b2b_tracer *tracer, void *param, b2b_param_free_cb free_param);
...
</programlisting>
		<para>
			This function asks the b2b_entities modules to create a new client 
			entity record and also create a new dialog by sending an initial message. 
			The parameters are all the values needed for the initial request to which
			the notify function and parameter are added.
			The b2b_cback parameter is a pointer to the callback that must be called when
			an event happens(receiving a reply or request) in the dialog created with
			this function.
			The add_dlginfo_f parameter is also a function pointer to a callback that will
			be called when a final success response will be received for the created dialog.
			The callback will receive as parameter the complete dialog information for the
			record. It should be stored and used when calling send_request or send_reply functions.
		</para>
		<para>
			The return value is an identifier for the record that will be mentioned when 
			calling other functions that represent actions in the dialog(send request,
			send reply).
		</para>
</section>

<section>
		<title>
		<function moreinfo="none">send_request</function>
		</title>
		<para>
			Field type:
		</para>
			<programlisting format="linespecific">
...
typedef int (*b2b_send_request_t)(enum b2b_entity_type ,str* b2b_key, str* method,
		str* extra_headers, str* body, b2b_dlginfo_t*);
...
</programlisting>
		<para>
			This function asks the b2b_entities modules to send a request inside a b2b dialog
			identified by b2b_key. The first parameter is the entity type and can have two values:
			B2B_SERVER and B2B_CLIENT. The second is the identifier returned by the create 
			function(server_new or client_new) and the next are the informations needed for
			the new request: method, extra_headers, body.
			The last parameter contains the dialog information - callid, to tag, from tag. These
			are needed to make a perfect match to of b2b_entities record for which a new request
			must be sent.
		</para>
		<para>
			The return value is 0 for success and a negative value for error.
		</para>
</section>

<section>
		<title>
		<function moreinfo="none">send_reply</function>
		</title>
		<para>
			Field type:
		</para>
			<programlisting format="linespecific">
...
typedef int (*b2b_send_reply_t)(enum b2b_entity_type et, str* b2b_key, int code, str* text,
		str* body, str* extra_headers, b2b_dlginfo_t* dlginfo);
...
</programlisting>
		<para>
			This function asks the b2b_entities modules to send a reply inside a b2b dialog
			identified by b2b_key. The first parameter is the entity type and can have two values:
			B2B_SERVER and B2B_CLIENT. The second is the identifier returned by the create 
			function(server_new or client_new) and the next are the informations needed for
			the new reply: code, text, body, extra_headers. The last parameter contains the
			dialog information used for matching the right record.
		</para>
		<para>
			The return value is 0 for success and a negative value for error.
		</para>
</section>

<section>
		<title>
		<function moreinfo="none">entity_delete</function>
		</title>
		<para>
			Field type:
		</para>
			<programlisting format="linespecific">
...
typedef void (*b2b_entity_delete_t)(enum b2b_entity_type et, str* b2b_key,
	 b2b_dlginfo_t* dlginfo);
...
</programlisting>
		<para>
		This function must be called by the upper level function to delete the
		records in b2b_entities. The records are not cleaned up by the b2b_entities
		module and the upper level module must take care to delete them.
		</para>
</section>

<section>
		<title>
		<function moreinfo="none">restore_logic_info</function>
		</title>
		<para>
			Field type:
		</para>
			<programlisting format="linespecific">
...
typedef int (*b2b_restore_linfo_t)(enum b2b_entity_type type, str* key,
		b2b_notify_t cback, void *param, b2b_param_free_cb free_param);
...
</programlisting>
		<para>
			This function is used at startup when loading the data from the database to
			restore the pointer to the callback function.
		</para>
</section>

<section>
		<title>
		<function moreinfo="none">update_b2bl_param</function>
		</title>
		<para>
			Field type:
		</para>
			<programlisting format="linespecific">
...
typedef int (*b2b_update_b2bl_param_t)(enum b2b_entity_type type, str* key,
		str* param, int replicate);
...
</programlisting>
		<para>
			This function can be used to change the logic param stored for an 
			entity ( useful in case an entity is moved between logic records).
		</para>
</section>

</chapter>

