textops_user.sgml

性能优秀的SIP Proxy

				g (global) or s (match newline don't treat it as end of line).
			</para>
			<para>
			're' - is regular expresion
			</para>
			<para>
			'repl' - is replacement string - may contain pseudo-varibales
			</para>
			<para>
			'flags' - substitution flags (i - ignore case, g - global)
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, 
		FAILURE_ROUTE, BRANCH_ROUTE.
		</para>
		<example>
		<title><function>subst_body</function> usage</title>
		<programlisting format="linespecific">
...
if ( subst_body('/^o=(.*) /o=$fU ') ) {};

...
</programlisting>
		</example>
	</section>

	<section>
		<title>
		<function moreinfo="none">append_to_reply(txt)</function>
		</title>
		<para>
		Append txt as header to the reply.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>txt</emphasis> - String which may contains
			pseudo-variables.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE, BRANCH_ROUTE.
		</para>
		<example>
		<title><function>append_to_reply</function> usage</title>
		<programlisting format="linespecific">
...
append_to_reply("Foo: bar\r\n");
append_to_reply("Foo: $rm at $Ts\r\n");
...
</programlisting>
		</example>
	</section>

	<section>
		<title>
		<function moreinfo="none">append_hf(txt)</function>
		</title>
		<para>
			Appends 'txt' as header after the last header field. 
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>txt</emphasis> - Header field to be appended. The
			value can contain pseudo-variables which will be replaced at run
			time.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, 
		FAILURE_ROUTE, BRANCH_ROUTE.
		</para>
		<example>
		<title><function>append_hf</function> usage</title>
		<programlisting format="linespecific">
...
append_hf("P-hint: VOICEMAIL\r\n");
append_hf("From-username: $fU\r\n");
...
</programlisting>
		</example>
	</section>

	<section>
		<title>
		<function moreinfo="none">append_hf(txt, hdr)</function>
		</title>
		<para>
		Appends 'txt' as header after first 'hdr' header field.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>txt</emphasis> - Header field to be appended. The
			value can contain pseudo-variables which will be replaced at run
			time.
			</para>
		</listitem>
		<listitem>
			<para><emphasis>hdr</emphasis> - Header name after which the 'txt'
			is appended.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, 
		FAILURE_ROUTE, BRANCH_ROUTE.
		</para>
		<example>
		<title><function>append_hf</function> usage</title>
		<programlisting format="linespecific">
...
append_hf("P-hint: VOICEMAIL\r\n", "Call-ID");
append_hf("From-username: $fU\r\n", "Call-ID");
...
</programlisting>
		</example>
	</section>

	<section>
		<title>
		<function moreinfo="none">insert_hf(txt)</function>
		</title>
		<para>
		Inserts 'txt' as header before the first header field.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>txt</emphasis> - Header field to be inserted. The
			value can contain pseudo-variables which will be replaced at run
			time.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, 
		FAILURE_ROUTE, BRANCH_ROUTE.
		</para>
		<example>
		<title><function>insert_hf</function> usage</title>
		<programlisting format="linespecific">
...
insert_hf("P-hint: VOICEMAIL\r\n");
insert_hf("To-username: $tU\r\n");
...
</programlisting>
		</example>
	</section>


	<section>
		<title>
		<function moreinfo="none">insert_hf(txt, hdr)</function>
		</title>
		<para>
		Inserts 'txt' as header before first 'hdr' header field.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>txt</emphasis> - Header field to be inserted. The
			value can contain pseudo-variables which will be replaced at run
			time.
			</para>
		</listitem>
		<listitem>
			<para><emphasis>hdr</emphasis> - Header name before which the 'txt'
			is inserted.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, 
		FAILURE_ROUTE, BRANCH_ROUTE.
		</para>
		<example>
		<title><function>insert_hf</function> usage</title>
		<programlisting format="linespecific">
...
insert_hf("P-hint: VOICEMAIL\r\n", "Call-ID");
insert_hf("To-username: $tU\r\n", "Call-ID");
...
</programlisting>
		</example>
	</section>

	<section>
		<title>
		<function moreinfo="none">append_urihf(prefix, suffix)</function>
		</title>
		<para>
		Append header field name with original <acronym>Request-URI</acronym> 
		in middle.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>prefix</emphasis> - string (usually at least 
			header field name).
			</para>
		</listitem>
		<listitem>
			<para><emphasis>suffix</emphasis> - string (usually at least 
			line terminator).
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, 
		BRANCH_ROUTE.
		</para>
		<example>
		<title><function>append_urihf</function> usage</title>
		<programlisting format="linespecific">
...
append_urihf("CC-Diversion: ", "\r\n");
...
</programlisting>
		</example>
	</section>

	<section>
		<title>
		<function moreinfo="none">is_present_hf(hf_name)</function>
		</title>
		<para>
		Return true if a header field is present in message.
		</para>
		<note>
		<para>
			The function is also able to distinguish the compact names. For
			exmaple <quote>From</quote> will match with <quote>f</quote>
		</para>
		</note>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>hf_name</emphasis> - Header field name.(long or 
			compact form)
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, 
		FAILURE_ROUTE, BRANCH_ROUTE.
		</para>
		<example>
		<title><function>is_present_hf</function> usage</title>
		<programlisting format="linespecific">
...
if (is_present_hf("From")) log(1, "From HF Present");
...
</programlisting>
		</example>
	</section>

	<section>
		<title>
		<function moreinfo="none">append_time()</function>
		</title>
		<para>
		Adds a time header to the reply of the request. You must use it
		before functions that are likely to send a reply, e.g., save()
		from 'registrar' module. Header format is: 
		<quote>Date: %a, %d %b %Y %H:%M:%S GMT</quote>, with the legend:
		<itemizedlist>
		<listitem>
			<para><emphasis>%a</emphasis> abbreviated week of day name (locale)
			</para>
		</listitem>
		<listitem>
			<para><emphasis>%d</emphasis> day of month as decimal number
			</para>
		</listitem>
		<listitem>
			<para><emphasis>%b</emphasis> abbreviated month name (locale)
			</para>
		</listitem>
		<listitem>
			<para><emphasis>%Y</emphasis> year with century
			</para>
		</listitem>
		<listitem>
			<para><emphasis>%H</emphasis> hour
			</para>
		</listitem>
		<listitem>
			<para><emphasis>%M</emphasis> minutes
			</para>
		</listitem>
		<listitem>
			<para><emphasis>%S</emphasis> seconds
			</para>
		</listitem>
		</itemizedlist>
		</para>
		<para>
		Return true if a header was succesfully appended.
		</para>
		<para>
		This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, 
		BRANCH_ROUTE.
		</para>
		<example>
		<title><function>append_time</function> usage</title>
		<programlisting format="linespecific">
...
append_time();
...
</programlisting>
		</example>
	</section>

	<section>
		<title>
		<function moreinfo="none">is_method(name)</function>
		</title>
		<para>
		Check if the method of the message matches the name. If name is a
		known method (invite, cancel, ack, bye, options, info, update, register,
		message, subscribe, notify, refer, prack), the function performs method
		ID testing (integer comparison) instead of ignore case string
		comparison.
		</para>
		<para>
		The 'name' can be a list of methods in the form of
		'method1|method2|...'. In this case, the function returns true if the
		SIP message's method is one from the list. IMPORTANT NOTE: in the list
		must be only methods defined in &ser; with ID (invite, cancel, ack,
		bye, options, info, update, register, message, subscribe, notify,
		refer, prack, publish; for more see:
		<ulink url="http://www.iana.org/assignments/sip-parameters">
			http://www.iana.org/assignments/sip-parameters</ulink>).
		</para>
		<para>
		If used for replies, the function tests the value of method field from
		CSeq header.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>name</emphasis> - SIP method name
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, 
		FAILURE_ROUTE, and BRANCH_ROUTE.
		</para>
		<example>
		<title><function>is_method</function> usage</title>
		<programlisting format="linespecific">
...
if(is_method("INVITE"))
{
    # process INVITEs here
}
if(is_method("OPTION|UPDATE"))
{
    # process OPTIONs and UPDATEs here
}
...
</programlisting>
		</example>
	</section>

	<section>
		<title>
		<function moreinfo="none">remove_hf(hname)</function>
		</title>
		<para>
		Remove from message all headers with name <quote>hname</quote>
		</para>
		<para>
		Returns true if at least one header is found and removed.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>hname</emphasis> - header name to be removed.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, 
		FAILURE_ROUTE and BRANCH_ROUTE.
		</para>
		<example>
		<title><function>remove_hf</function> usage</title>
		<programlisting format="linespecific">
...
if(remove_hf("User-Agent"))
{
    # User Agent header removed
}
...
</programlisting>
		</example>
	</section>

	<section>
		<title>
		<function moreinfo="none">has_body()</function>,
		<function moreinfo="none">has_body(mime)</function>
		</title>
		<para>
		The function returns <emphasis>true</emphasis> if the SIP message
		has a body attached. The checked includes also the 
		<quote>Content-Lenght</quote> header presence and value.
		</para>
		<para>
		If a paramter is given, the mime described will be also checked against
		the <quote>Content-Type</quote> header.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>mime</emphasis> - mime to be checked against the 
				<quote>Content-Type</quote> header. If not present or 0, this
				check will be disabled.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, 
		FAILURE_ROUTE and BRANCH_ROUTE.
		</para>
		<example>
		<title><function>has_body</function> usage</title>
		<programlisting format="linespecific">
...
if(has_body("application/sdp"))
{
    # do interesting stuff here
}
...
</programlisting>
		</example>
	</section>





	</section>
	<section>
		<title>Known Limitations</title>
		<para>
			Search functions are applied to the original request,
			i.e., they ignore all changes resulting from message
			processing in &ser; script.
		</para>
	</section>
</chapter>

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