cpl-c_user.sgml

来自「性能优秀的SIP Proxy」· SGML 代码 · 共 627 行 · 第 1/2 页

			</para>
			<para>
				<emphasis>
					Default value of this parameter is empty string.
				</emphasis>
			</para>
			<example>
				<title>Set <varname>realm_prefix</varname> parameter</title>
				<programlisting format="linespecific">
...
modparam("cpl_c","realm_prefix","sip.")
...
</programlisting>
			</example>
		</section>
		<section>
			<title><varname>timer_avp</varname> (string)</title>
			<para>
				Full specification (ID, NAME, ALIAS) of the AVP to be used to 
				set the value of the Final Response INVITE timeout - it's 
				used by the TIMEOUT attribute from the PROXY tag.
			</para>
			<para>
				NOTE: take care and syncronize this value with the similar
				parameters in TM module.
			</para>
			<para>
				<emphasis>
					Default value of this parameter is NULL.
				</emphasis>
			</para>
			<example>
				<title>Set <varname>timer_avp</varname> parameter</title>
				<programlisting format="linespecific">
...
modparam("cpl_c","timer_avp","i:14")
...
</programlisting>
			</example>
		</section>
		<section>
			<title><varname>nat_flag</varname> (int)</title>
			<para>
				Sets the flag used for marking calls via NAT. Used by lookup
				tag when retrieving a contact behind a NAT (this flag will be 
				set).
			</para>
			<para>
				<emphasis>
					Default value of this parameter is 6.
				</emphasis>
			</para>
			<example>
				<title>Set <varname>nat_flag</varname> parameter</title>
				<programlisting format="linespecific">
...
modparam("cpl_c","nat_flag",4)
...
</programlisting>
			</example>
		</section>
		<section>
			<title><varname>lookup_domain</varname> (string)</title>
			<para>
				Used by lookup tag to indicate where to perform user location.
				Basically this is the name of the usrloc domain (table) where
				the user registrations are kept.
			</para>
			<para>
				If set to empty string, the lookup node will be disabled - no
				user location will be performed.
			</para>
			<para>
				<emphasis>
					Default value of this parameter is NULL.
				</emphasis>
			</para>
			<example>
				<title>Set <varname>lookup_domain</varname> parameter</title>
				<programlisting format="linespecific">
...
modparam("cpl_c","lookup_domain","location")
...
</programlisting>
			</example>
		</section>
		<section>
			<title><varname>lookup_append_branches</varname> (int)</title>
			<para>
				Tells if the lookup tag should append branches (to do parallel
				forking) if user_location lookup returns more than one contact.
				Set it to a non zero value to enable parallel forking for
				location lookup tag.
			</para>
			<para>
				<emphasis>
					Default value of this parameter is 0.
				</emphasis>
			</para>
			<example>
				<title>Set <varname>lookup_append_branches</varname> 
					parameter</title>
				<programlisting format="linespecific">
...
modparam("cpl_c","lookup_append_branches",1)
...
</programlisting>
			</example>
		</section>
		<section>
			<title><varname>use_domain</varname> (integer)</title>
			<para>
				Indicates if the domain part of the URI should be used in 
				user identification (otherwise only username part will be
				used).
			</para>
			<para>
				<emphasis>
					Default value is <quote>0 (disabled)</quote>.
				</emphasis>
			</para>
			<example>
				<title>Set <varname>use_domain</varname> parameter</title>
				<programlisting format="linespecific">
...
modparam("cpl_c","use_domain",1)
...
</programlisting>
			</example>
		</section>

	</section>


	<section>
		<title>Exported Functions</title>
		<section>
			<title>
				<function moreinfo="none">cpl_run_script(type,mode)</function>
			</title>
			<para>
				Starts the execution of the CPL script. The user name is 
				fetched from new_uri or requested uri or from To header -in 
				this order- (for incoming execution) or from FROM header (for 
				outgoing execution).
				Regarding the stateful/stateless message processing, the
				function  is very flexible, being able to run in different 
				modes (see below the"mode" parameter).
				Normally this function will end script execution.  There is no 
				guaranty that the CPL script interpretation ended when &ser; 
				script ended also (for the same INVITE ;-)) - this can happen 
				when the CPL script does a PROXY and the script interpretation 
				pause after proxying and it will be resume when some reply is
				received (this can happen in a different process of SER). 
				If the function returns to script, the SIP server should 
				continue with the normal behavior as if no script existed.
				When some error is returned, the function itself haven't sent 
				any SIP error reply (this can be done from script).
			</para>
			<para>Meaning of the parameters is as follows:</para>
			<itemizedlist>
			<listitem>
				<para><emphasis>type</emphasis> - which part of the script 
				should be run; set it to "incoming" for having the incoming 
				part of script executed (when an INVITE is received) or to 
				"outgoing" for running the outgoing part of script (when a 
				user is generating an INVITE - call).
				</para>
			</listitem>
			<listitem>
				<para><emphasis>mode</emphasis> - sets the interpreter mode as
				stateless/stateful behavior. The following modes are accepted:
				</para>
				<itemizedlist>
				<listitem>
					<para>
					<emphasis>IS_STATELESS<emphasis> - the current INVITE has 
					no transaction created yet. All replies (redirection or 
					deny) will be done is a stateless way. The execution will 
					switch to stateful only when proxy is done. So, if the 
					function returns, will be in stateless mode.
					</para>
				</listitem>
				<listitem>
					<para>
					<emphasis>IS_STATEFUL<emphasis> - the current INVITE has 
					already a transaction associated. All signaling operations
					(replies or proxy) will be done in stateful way.So, if
					the function returns, will be in stateful mode.
					</para>
				</listitem>
				<listitem>
					<para>
					<emphasis>FORCE_STATEFUL<emphasis> - the current INVITE 
					has no transaction created yet. All signaling operations
					will be done is a stateful way (on signaling, the
					transaction will be created from within the interpreter).
					So, if the function returns, will be in stateless mode.
					</para>
				</listitem>
				</itemizedlist>
				<para>
				<emphasis>HINT</emphasis>: is_stateful is very 
				difficult to manage from the routing script (script processing
				can continue in stateful mode); is_stateless is the fastest and
				less resources consumer (transaction is created only if
				proxying is done), but there is minimal protection against
				retransmissions (since replies are send stateless);
				force_stateful is a good compromise - all signaling is done
				stateful (retransmission protection) and in the same time, if
				returning to script, it will be in stateless mode (easy to
				continue the routing script execution)
				</para>
			</listitem>
			</itemizedlist>
			<para>
			This function can be used from REQUEST_ROUTE.
			</para>
			<example>
				<title><function>cpl_run_script</function> usage</title>
				<programlisting format="linespecific">
...
cpl_run_script("incoming","force_stateful");
...
</programlisting>
			</example>
		</section>
		<section>
			<title>
				<function moreinfo="none">cpl_process_register()</function>
			</title>
			<para>
				This function MUST be called only for REGISTER requests. It 
				checks if the current REGISTER request is related or not with 
				CPL script upload/download/ remove. If it is, all the needed 
				operation will be done. For checking if the REGISTER is CPL 
				related, the function looks fist to "Content-Type" header. If 
				it exists and has a the mime type set to "application/cpl+xml" 
				means this is a CPL script upload/remove operation. The 
				distinction between to case is made by looking at 
				"Content-Disposition" header; id its value is 
				"script;action=store", means it's an upload; if it's 
				"script;action=remove", means it's a remove operation; other 
				values are considered to be errors. If no "Content-Type" 
				header is present, the function looks to "Accept" header and 
				if it contains the "*" or "application/cpl-xml" the request 
				it will be consider one for downloading CPL scripts.
				The functions returns to script only if the the REGISTER is 
				not related to CPL. In other case, the function will send by 
				itself the necessary replies (stateless - using sl), including 
				for errors.
			</para>
			<para>
			This function can be used from REQUEST_ROUTE.
			</para>
			<example>
				<title><function>cpl_process_register</function> usage</title>
				<programlisting format="linespecific">
...
if (method=="REGISTER") {
	cpl_process_register();
}
...
</programlisting>
			</example>
		</section>
		<section>
			<title>
				<function moreinfo="none">cpl_process_register_norpl()
					</function>
			</title>
			<para>
				Same as <quote>cpl_process_register</quote> without 
				internally generating the reply. All information (script) is
				appended to the reply but without sending it out.
			</para>
			<para>
				Main purpose of this function is to allow integration 
				between CPL and UserLocation services via same REGISTER
				messages.
			</para>
			<para>
			This function can be used from REQUEST_ROUTE.
			</para>
			<example>
				<title><function>cpl_process_register_norpl</function> usage
					</title>
				<programlisting format="linespecific">
...
if (method=="REGISTER") {
	cpl_process_register();
	# continue with usrloc part
	save("location");
}
...
</programlisting>
			</example>
		</section>
	</section>


	<section>
		<title>Installation & Running</title>
		<para>Notes about installation and running.</para>
	</section>
</chapter>

<!-- Keep this element at the end of the file
Local Variables:
sgml-parent-document: ("cpl-c.sgml" "Book" "chapter")
End:
-->