Skip to content

Commit

Permalink
ldap: docs - removed trailing spaces
Browse files Browse the repository at this point in the history
  • Loading branch information
@miconda
miconda committed Nov 13, 2023
1 parent 9adfc9c commit b0f99cb
Show file tree
Hide file tree
Showing 2 changed files with 57 additions and 57 deletions.
50 changes: 25 additions & 25 deletions src/modules/ldap/doc/ldap_admin.xml
View file
Expand Up @@ -13,11 +13,11 @@
<section>
<title>Overview</title>

<para>The LDAP module implements an LDAP search interface for &kamailio;.
It exports script functions to perform an LDAP search operation and to
<para>The LDAP module implements an LDAP search interface for &kamailio;.
It exports script functions to perform an LDAP search operation and to
store the search results as &kamailio; AVPs. This allows for using LDAP
directory data in the &kamailio; SIP message routing script.</para>

<para>The following features are offered by the LDAP module:</para>
<itemizedlist>
<listitem>
Expand All @@ -41,18 +41,18 @@
<listitem>
<para>Module API for LDAP search operations that can be used by other &kamailio; modules</para>
</listitem>
</itemizedlist>
</itemizedlist>

<para>The module implementation makes use of the open source <emphasis>OpenLDAP</emphasis> library available
on most UNIX/Linux platforms. Besides LDAP server failover and automatic reconnect, this module can handle
multiple LDAP sessions concurrently allowing access to data stored on different LDAP servers. Each &kamailio;
worker process maintains one LDAP TCP connection per configured LDAP server. This enables parallel execution
of LDAP requests and offloads LDAP concurrency control to the LDAP server(s).</para>

<para>An LDAP search module API is provided that can be used by other &kamailio; modules. A module using this
API does not have to implement LDAP connection management and configuration, while still having access
to the full OpenLDAP API for searching and result handling.</para>
to the full OpenLDAP API for searching and result handling.</para>

<para>Since LDAP server implementations are optimized for fast read access they are a good choice to store SIP
provisioning data. Performance tests have shown that this module achieves lower data access times and higher
call rates than other database modules like e.g. the &kamailio; MYSQL module.</para>
Expand All @@ -73,7 +73,7 @@
operation. It expects an LDAP URL as input which includes the LDAP session name and search parameters.
The section <xref linkend="ldap-urls"/> provides a quick overview on LDAP URLs.
</para>

<para>
The result of a LDAP search is stored internally and can be accessed with one of the
<varname>ldap_result*</varname> functions. <varname>ldap_result</varname> (<xref linkend="ldap-result-fn"/>)
Expand All @@ -82,7 +82,7 @@
values using regular expression matching. Finally, <varname>ldap_result_next</varname>
(<xref linkend="ldap-result-next-fn"/>) allows using LDAP search queries that return more than one LDAP entry.
</para>

<para>
All <varname>ldap_result*</varname> functions always access the LDAP result set from the last
<varname>ldap_search</varname> call. This should be kept in mind when calling <varname>ldap_search</varname>
Expand Down Expand Up @@ -194,11 +194,11 @@

<note>
<para>Non-URL characters in an LDAP URL have to be escaped using
percent-encoding (refer to section 2.1 of RFC 4516). In particular
percent-encoding (refer to section 2.1 of RFC 4516). In particular
this means that any "?" character in an LDAP URL component must be
written as "%3F", since "?" is used as a URL delimiter.</para>
<para>The exported function <varname>ldap_filter_url_encode</varname>
(<xref linkend="ldap-filter-url-encode-fn"/>)
(<xref linkend="ldap-filter-url-encode-fn"/>)
implements RFC 4515/4516 LDAP search filter and URL escaping
rules.</para>
</note>
Expand Down Expand Up @@ -299,7 +299,7 @@ ldap_client_bind_timeout = 500
<programlisting format="linespecific">
ldap_server_url = "ldap://localhost"
ldap_server_url = "ldaps://ldap.example.com:7777"
ldap_server_url = "ldap://ldap1.example.com,
ldap_server_url = "ldap://ldap1.example.com,
ldap://ldap2.example.com:80389"
</programlisting>
</example>
Expand Down Expand Up @@ -364,7 +364,7 @@ ldap_server_url = "ldap://ldap1.example.com,

<listitem>
<para>LDAP TCP connect timeout in milliseconds. Setting this
parameter to a low value enables fast failover if <varname>ldap_server_url</varname> contains more
parameter to a low value enables fast failover if <varname>ldap_server_url</varname> contains more
than one LDAP server addresses.</para>

<para>Default value: 1000 (one second)</para>
Expand Down Expand Up @@ -564,7 +564,7 @@ ldap://ldap_1/dc=example,dc=com?
<para>
This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE, and ONREPLY_ROUTE.
</para>

<example>
<title>Example Usage</title>

Expand Down Expand Up @@ -609,7 +609,7 @@ ldap_result("telephoneNumber/$avp(s:tel_number)");
part of an attribute value should be stored as AVP.</para>

<para>
An AVP can either be of type string or integer. As default,
An AVP can either be of type string or integer. As default,
<varname>ldap_result</varname> stores LDAP attribute values as AVP of type string.
The optional <varname>avp_type</varname> parameter can be used to explicitly specify
the type of the AVP. It can be either <varname>str</varname> for string, or
Expand All @@ -618,7 +618,7 @@ ldap_result("telephoneNumber/$avp(s:tel_number)");
attribute values to integer. In this case, the values are only stored as AVP if the
conversion to integer is successful.
</para>

<variablelist>
<title>Function Parameters:</title>

Expand All @@ -641,7 +641,7 @@ ldap_result("telephoneNumber/$avp(s:tel_number)");
<varname>$avp(i:12)</varname></para>
</listitem>
</varlistentry>

<varlistentry>
<term>avp_type</term>

Expand Down Expand Up @@ -702,7 +702,7 @@ ldap_result("telephoneNumber/$avp(s:tel_number)");
<para>
This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE, and ONREPLY_ROUTE.
</para>

<example>
<title>Example Usage</title>

Expand All @@ -725,7 +725,7 @@ if (!ldap_result("SIPIdentityServiceLevel/$avp(s:service_level)"))
# internal error
sl_send_reply("500", "Internal server error");
exit;
default:
default:
exit;
}
}
Expand Down Expand Up @@ -819,7 +819,7 @@ ldap_result("SIPIdentitySIPURI/$avp(i:10)", "/^[^@]+@(.+)$/\1/");
<para>
This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE, and ONREPLY_ROUTE.
</para>

<example>
<title>Example Usage</title>

Expand Down Expand Up @@ -913,7 +913,7 @@ if (ldap_result_next())
if (ldap_result_next())
{
ldap_result("telephonenumber/$avp(s:tel4)");
}
}
...
</programlisting>
</example>
Expand All @@ -925,7 +925,7 @@ if (ldap_result_next())
<para>This function applies the following escaping rules to
<varname>string</varname> and stores the result in AVP
<varname>avp_spec</varname>:</para>

<table>
<title>ldap_filter_url_encode() escaping rules</title>

Expand Down Expand Up @@ -986,7 +986,7 @@ if (ldap_result_next())
</table>

<para>The string stored in AVP <varname>avp_spec</varname> can be safely used in an LDAP
URL filter string.</para>
URL filter string.</para>

<variablelist>
<title>Function Parameters:</title>
Expand Down Expand Up @@ -1052,7 +1052,7 @@ if (!ldap_filter_url_encode("cn=$avp(s:name)", "$avp(s:name_esc)"))
xlog("L_INFO", "encoded LDAP filter component: [$avp(s:name_esc)]\n");

if (ldap_search(
"ldap://h350/ou=commObjects,dc=example,dc=com??sub?($avp(s:name_esc))"))
"ldap://h350/ou=commObjects,dc=example,dc=com??sub?($avp(s:name_esc))"))
{ ... }
...
</programlisting>
Expand Down
64 changes: 32 additions & 32 deletions src/modules/ldap/doc/ldap_devel.xml
View file
Expand Up @@ -16,15 +16,15 @@
<para>
The LDAP module API can be used by other &kamailio; modules to implement
LDAP search functionality. This frees the module implementer from having
to care about LDAP connection management and configuration.
to care about LDAP connection management and configuration.
</para>
<para>
In order to use this API, a module has to load the API using the <varname>load_ldap_api</varname>
function which returns a pointer to a <varname>ldap_api</varname> structure. This structure
includes pointers to the API functions described below. The LDAP module source file
<varname>api.h</varname> includes all declarations needed to load the API, it has to
be included in the file that use the API. Loading the API is typically done inside a
module's <varname>mod_init</varname> call as the following example shows:
module's <varname>mod_init</varname> call as the following example shows:
<example>
<title>Example code fragment to load LDAP module API</title>
<programlisting><![CDATA[
Expand Down Expand Up @@ -53,7 +53,7 @@ static int mod_init(void)
}
...
]]>
]]>
</programlisting>
</example>
</para>
Expand All @@ -63,20 +63,20 @@ static int mod_init(void)
<title>Example LDAP module API function call</title>
<programlisting><![CDATA[
...
rc = ldap_api.ldap_rfc4515_escape(str1, str2, 0);
...
]]>
rc = ldap_api.ldap_rfc4515_escape(str1, str2, 0);
...
]]>
</programlisting>
</example>
</example>
</para>

</section>

<section>
<title>API Functions</title>

<section>
<title>ldap_params_search</title>
<para>
Expand All @@ -99,7 +99,7 @@ typedef int (*ldap_params_search_t)(int* _ld_result_count,
<listitem>
<para>
The function stores the number of returned LDAP entries
in <varname>_ld_result_count</varname>.
in <varname>_ld_result_count</varname>.
</para>
</listitem>
</varlistentry>
Expand Down Expand Up @@ -143,13 +143,13 @@ typedef int (*ldap_params_search_t)(int* _ld_result_count,
<term>char* _filter</term>
<listitem>
<para>
LDAP search filter string according to RFC 4515.
LDAP search filter string according to RFC 4515.
<varname>printf</varname> patterns in this string do get replaced with
the function arguments' values following the <varname>_filter</varname> argument.
</para>
</listitem>
</varlistentry>

</variablelist>
<variablelist>
<title>Return Values:</title>
Expand All @@ -171,7 +171,7 @@ typedef int (*ldap_params_search_t)(int* _ld_result_count,
</varlistentry>
</variablelist>
</section>

<section>
<title>ldap_url_search</title>
<para>
Expand Down Expand Up @@ -221,7 +221,7 @@ typedef int (*ldap_url_search_t)(char* _ldap_url,
</varlistentry>
</variablelist>
</section>

<section>
<title>ldap_result_attr_vals</title>
<para>
Expand All @@ -237,7 +237,7 @@ typedef int (*ldap_url_search_t)(char* _ldap_url,
<programlisting><![CDATA[
typedef int (*ldap_result_attr_vals_t)(str* _attr_name,
struct berval ***_vals);
typedef struct berval {
ber_len_t bv_len;
char *bv_val;
Expand Down Expand Up @@ -291,12 +291,12 @@ typedef struct berval {
</varlistentry>
</variablelist>
</section>

<section>
<title>ldap_value_free_len</title>
<para>
Function used to free memory allocated by <varname>ldap_result_attr_vals</varname>.
The <varname>berval</varname> structure is defined in OpenLDAP's
The <varname>berval</varname> structure is defined in OpenLDAP's
<varname>ldap.h</varname>, which has to be included.
</para>
<programlisting><![CDATA[
Expand All @@ -320,7 +320,7 @@ typedef struct berval {
</varlistentry>
</variablelist>
</section>

<section>
<title>ldap_result_next</title>
<para>
Expand Down Expand Up @@ -359,7 +359,7 @@ typedef int (*ldap_result_next_t)();
</varlistentry>
</variablelist>
</section>

<section>
<title>ldap_str2scope</title>
<para>
Expand Down Expand Up @@ -400,7 +400,7 @@ typedef int (*ldap_str2scope_t)(char* scope_str);
</varlistentry>
</variablelist>
</section>

<section>
<title>ldap_rfc4515_escape</title>
<para>
Expand Down Expand Up @@ -457,7 +457,7 @@ typedef int (*ldap_rfc4515_escape_t)(str *sin, str *sout, int url_encode);
</varlistentry>
</variablelist>
</section>

<section>
<title>get_ldap_handle</title>
<para>
Expand Down Expand Up @@ -509,15 +509,15 @@ typedef int (*get_ldap_handle_t)(char* _lds_name, LDAP** _ldap_handle);
</varlistentry>
</variablelist>
</section>

<section>
<title>get_last_ldap_result</title>
<para>
Returns the OpenLDAP LDAP handle and OpenLDAP result handle of the last LDAP search
Returns the OpenLDAP LDAP handle and OpenLDAP result handle of the last LDAP search
operation. These handles can be used as input for OpenLDAP LDAP result API functions.
<varname>LDAP</varname> and <varname>LDAPMessage</varname> structures are defined in
<varname>LDAP</varname> and <varname>LDAPMessage</varname> structures are defined in
OpenLDAP's <varname>ldap.h</varname>, which has to be included.
</para>
</para>
<programlisting><![CDATA[
typedef void (*get_last_ldap_result_t)
(LDAP** _last_ldap_handle, LDAPMessage** _last_ldap_result);
Expand Down Expand Up @@ -552,7 +552,7 @@ typedef void (*get_last_ldap_result_t)
</para>
<programlisting><![CDATA[
...
int rc, ld_result_count, scope = 0;
char* sip_username = "test";
Expand Down Expand Up @@ -594,9 +594,9 @@ if (ld_result_count < 1)
}
/*
* get password attribute value
* get password attribute value
*/
struct berval **attr_vals = NULL;
str ldap_pwd_attr_name = str_init("SIPIdentityPassword");
str res_password;
Expand Down Expand Up @@ -624,7 +624,7 @@ LM_INFO("Password for user [%s]: [%s]\n", sip_username, res_password.s);
...
return 0;
return 0;
]]>
</programlisting>
</section>
Expand Down

0 comments on commit b0f99cb

Please sign in to comment.