ldap_server_conf_save()-- Store Server Information into Local Configuration

Syntax #include <ldap.h> typedef struct LDAP_Server_Info { char *lsi_host; /* LDAP server's hostname */ unsigned short lsi_port; /* LDAP port */ char *lsi_suffix; /* Server's LDAP suffix */ char *lsi_query_key; /* service_key[.edomain]*/ char *lsi_dns_domain; /* Publishing DNS domain */ int lsi_replica_type;/* master or replica */ #define LDAP_LSI_MASTER 1 /* LDAP Master */ #define LDAP_LSI_REPLICA 2 /* LDAP Replica */ int lsi_sec_type; /* SSL or non-SSL */ #define LDAP_LSI_NOSSL 1 /* Non-SSL */ #define LDAP_LSI_SSL 2 /* Secure Server */ unsigned short lsi_priority; /* Server priority */ unsigned short lsi_weight; /* load balancing weight */ char *lsi_vendor_info; /* vendor information */ char *lsi_info; /* LDAP Info string */ struct LDAP_Server_Info *prev; /* linked list previous ptr */ struct LDAP_Server_Info *next; /* linked list next ptr */ } LDAPServerInfo; int ldap_server_conf_save( char *filename, unsigned long ttl, LDAPServerInfo *server_info_listp)); Threadsafe: Yes

Theldap_server_conf_save() API is used to store server information into local configuration. The format for specifying the server information is identical to the format returned from the locator API.

The application that writes information into the configuration file can specify an optional time-to-live for the information stored in the file. When an application uses the locator API to access DNS server information, the configuration file is considered to be stale if:

  <date/time_file_last_updated + ttl>  current_date/time 

If the application uses the default behavior for using the configuration file, it will bypass a stale configuration file and attempt to find all needed information from DNS. Otherwise, the ttl should be set to zero (indefinite ttl), in which case the information is considered to be good indefinitely.

Setting a non-zero ttl is most useful when an application (or other mechanism) exists for refreshing the local configuration file on a periodic basis.

Note that sub-second response time can be expected in many cases, when using UDP to query DNS. Since most applications will get the server information during initialization, repetitive invocation of the locator API is usually unnecessary.

By default, the configuration file is stored at /QIBM/UserData/OS400/DirSrv/ldap_server_info.conf

Authorities and Locks

   Object Authorities 
       The caller must have Execute (*X) authority to each directory in the path
       name preceding the name of the configuration file.
       The caller must have write (*W) authority to the configuration file. 

Parameters

server_info_listpp

(input) Specifies the address that will be set to point to a linked list of LDAPServerInfo structures. Each LDAPServerInfo structure defined in the list contains server information obtained from either:

• DNS
• Local configuration

Upon successful return from ldap_server_locate(), server_info_listpp points to a linked list of LDAPServerInfo structures. The LDAPServerInfo structure (as defined above), contains the following fields:

lsi_host

Fully-qualified hostname of the target server (NULL-terminated string).

lsi_port

Integer representation of the LDAP server's port.

lsi_suffix

String that specifies a supported suffix for the LDAP server (NULL-terminated string).

lsi_query_key

Specifies the The eNetwork domain to which the LDAP server belongs, prefixed by the service key. For example, if service key is ldap and eNetwork domain is sales, then lsi_query_key would be set to ldap.sales. If the server is not associated with an eNetwork domain (as published in DNS), then lsi_query_key consists solely of the service key value.

lsi_dns_domain

DNS domain in which the LDAP server was published. For example, the DNS search may have been for ldap.sales.tcp.austin.ibm.com, but the resulting server(s) has a fully-qualified DNS host name of ldap2.raleigh.ibm.com. In this example, lsi_host would be set to ldap2.raleigh.ibm.com whilst lsi_dns_domain would be set to austin.ibm.com. The actual domain in which the server was "published" may be of interest, particularly when multiple DNS domains are configured (or supplied as input).

lsi_replica_type

Specifies the type of server, LDAP_LSI_MASTER or LDAP_LSI_REPLICA. If set to zero, the type is unknown.

lsi_sec_type

Specifies the port's security type, LDAP_LSI_NOSSL or LDAP_LSI_SSL. This value is derived from the "ldap" or "ldaps" prefix on the LDAP URL. If the LDAP URL is not defined, the security type is unknown and lsi_sectype is set to zero.

lsi_priority

The priority value obtained from the SRV RR (or the "pseudo-SRV" TXT RR). Set to zero if unknown or not available.

lsi_weight

The weight value obtained from the SRV RR (or the "pseudo-SRV" TXT RR). Set to zero if unknown or not available.

lsi_vendor_info

NULL-terminated string obtained from the ldapvendor TXT RR (if defined). May be used to identify the LDAP server vendor/version information.

lsi_info

NULL-terminated information string obtained from the ldapinfo TXT RR (if defined). If not defined, lsi_info is set to NULL. This information string can be used by the LDAP or network administrator to publish additional information about the target LDAP server.

filename

(input) Specifies an alternative configuration filename. Specify NULL to get the default filename and location.

ttl

(input) Specifies the time-to-live (in minutes) for server information saved in the configuration file. Set ttl to zero if it is intended to be a permanent repository of information.

When the ldap_server_locate() API is used to access the configuration file with search_source set to LDAP_LSI_CONF_ONLY, and the configuration file has not been refreshed in ttl minutes, then LDAP_TIMEOUT error code is returned.

When the ldap_server_locate() API is used to access the configuration file with search_source set to LDAP_LSI_CONF_DNS, and the configuration file has not been refreshed in ttl minutes, then network DNS is accessed to obtain server information.

Return Value

LDAP_SUCCESS

if the request was successful.

another LDAP error code

if the request was not successful.

Error Conditions

If ldap_server_conf_save() is not successful, an error code will be returned. See LDAP Client API Error Conditions for possible LDAP error code values.

Error Messages

    The following message may be set from this function.
    CPF3CF2 E  Error(s) occurred during running of ldap_server_conf_save API.

Related Information

    ldap_server_locate() -- Locate Suitable LDAP Servers. 
    ldap_server_free_list() -- Free the List of LDAP Servers.