3 Basic Usage

To load mfmod_ldap into your MFL program, first make sure that mailfromd search path (see include search path in Mailfromd Manual) contains directory where the ldap.mf interface file is installed, and the search path for dynamically loaded modules (see mfmod-path in Mailfromd Manual) contains directory where the loaded library mfmod_ldap.so resides. Once these prerequisites are met, add the require statement:

require 'ldap'

To look up objects in the database, use the search function. It takes two mandatory and arbitrary number of optional arguments. First argument supplies the base DN to use. If an empty string is given, the basedn value from ldap.conf will be used instead. Second argument gives the filter string to use. Additional arguments specify the names of attributes to retrieve.

For example, the following statement looks for objects with the uid attribute matching the variable user and retrieves the cn and telephoneNumber attributes.

number rd search('ou=people,dc=example,dc=org',
                 "(uid=%user)", "cn", "telephoneNumber")

The function returns result set descriptor, a non-negative integer value identifying the result set returned by the search. The result set has zero or more entries describing objects in the database that satisfy the filter. The number of entries can be obtained by calling search_result_count_entries. At each moment of time, there is a current entry, from which attributes and their values can be obtained. To switch to the next entry in the set and make it current, use the search_result_next_entry function.

The following example illustrates the usual approach for scanning result sets: it prints the values of ‘cn’ attributes for each object in the database.

number rd search('', '(objectClass=*)', 'cn')
loop
do
  echo search_result_attr_value_get(rd, 'cn', 0)
done while search_result_next_entry(rd)
search_result_free(rd)

The search_result_attr_value_get function retrieves the value of the attribute named in its second argument. Its third arguments gives the index of the value, if the attribute can have multiple values.

Notice the use of search_result_free function after the loop: when the result is no longer needed, it must be disposed of using that function. It reclaims the resources associated with the result set and returns its descriptor to the pool of available ones.