Summary: Isode provides a number of APIs which allow integrators and product developers to build components that allow client programs to connect to, query and modify data in the directory.
Directory Referrals
const DS_ReferralDS_ReferralList_GetFirst (const DS_ReferralList *referral_list)
 Get the first referral or continuation reference (if there is one) in a list of referrals. More...
 
const DS_ReferralDS_Referral_GetNext (const DS_Referral *referral)
 Get the next referral or continuation reference (if any) in a list of referrals. More...
 
const DS_ReferralAddressDS_Referral_GetFirstAddress (const DS_Referral *referral)
 Get the first referral address from a DS_Referral. More...
 
const DS_ReferralAddressDS_ReferralAddress_GetNext (const DS_ReferralAddress *referral_address)
 Get the next referral address (if any) in a list of referral addresses. More...
 
DS_Status DS_Referral_GetTargetDN (const DS_Referral *referral, const DS_DN **dn_p)
 Get the target DN from the given DS_Referral. More...
 
DS_Status DS_ReferralAddress_GetDSADN (const DS_ReferralAddress *referral_address, const DS_DN **dn_p)
 Get the DSA DN from the given DS_ReferralAddress. More...
 
DS_Status DS_ReferralAddress_GetBindAddress (const DS_ReferralAddress *referral_address, const char **address_p)
 Get the bind address from the given DS_ReferralAddress. More...
 

Detailed Description

Certain operations may require access to entry information which is not held on the local directory. Depending on configuration, it may be that rather than communicating with other directories to resolve the request, the directory will return information about the remote directories to the DUA, so that it can decide whether or not to establish connections to the other directory server(s) in order to complete the operation.

Typically, this situation results in a referral being returned to the client. This is an error status (i.e. the operation was not successful), and corresponds to the error type of DS_E_REFERRAL inside an Indication.

For a search operation, it may be that the set of matching entries spans multiple directories. In this case, the result of the search will include any entries which the directory itself is able and willing to return, as well as a set of continuation references representing other locations where the client should look in order to obtain a complete set of results.

Referrals and continuation references are both represented by a DS_Referral structure, which records the "target dn" for the referral or reference; that is, the DN which the directory was unable to resolve, and a set of DS_ReferralAddress structures containing information about other directories which may be able to satisfy the failing request.

A DS_ReferralAddress contains a bind_address, which is suitable for using with DS_BindSync_Simple etc., and, if available, a dsa_dn which will be suitable for using with DS_BindSync_Strong.

For an operation which fails where the Indication contains an error type of DS_E_REFERRAL, the Indication will also contain information about the referral.

For a successful search operation, the Indication will contain a list of continuation references (if any were returned by the directory server). Note that the Indication will not in this case contain a DS_E_REFERRAL error, but it may contain another failure status such as DS_E_SVC_TIMELIMITEXCEEDED).

A referral error may be returned in the case of a search operation for which the base object is not available.

See also
DS_Indication_GetReferralList
DS_Indication_GetContinuationReferences

Function Documentation

const DS_Referral* DS_ReferralList_GetFirst ( const DS_ReferralList referral_list)

Get the first referral or continuation reference (if there is one) in a list of referrals.

Parameters
[in]referral_listsource referral list.
Return values
NULLIf there are no referrals in the list
non-NULLPointer to the first referral in the list
Since
DSAPI_VERSION 2016
const DS_Referral* DS_Referral_GetNext ( const DS_Referral referral)

Get the next referral or continuation reference (if any) in a list of referrals.

Parameters
[in]referralcurrent referral in the list.
Return values
NULLIf there are no more referrals in the list
non-NULLPointer to the next referral in the list
Since
DSAPI_VERSION 2016
const DS_ReferralAddress* DS_Referral_GetFirstAddress ( const DS_Referral referral)

Get the first referral address from a DS_Referral.

Parameters
[in]referrala DS_Referral.
Return values
apointer to the first DS_ReferralAddress in the list
Since
DSAPI_VERSION 2016
const DS_ReferralAddress* DS_ReferralAddress_GetNext ( const DS_ReferralAddress referral_address)

Get the next referral address (if any) in a list of referral addresses.

Parameters
[in]referral_addresscurrent address in the list.
Return values
NULLIf there are no more referral addresses in the list
non-NULLPointer to the next referral address in the list
Since
DSAPI_VERSION 2016
DS_Status DS_Referral_GetTargetDN ( const DS_Referral referral,
const DS_DN **  dn_p 
)

Get the target DN from the given DS_Referral.

Parameters
[in]referralTarget referral.
[out]dn_pA pointer to the DN which the directory has been unable to resolve, and which should be used when following the referral.
Return values
DS_E_BADPARAMEither referral or dn_p was NULL
DS_E_NOERRORA DS_DN was returned
Since
DSAPI_VERSION 2016
DS_Status DS_ReferralAddress_GetDSADN ( const DS_ReferralAddress referral_address,
const DS_DN **  dn_p 
)

Get the DSA DN from the given DS_ReferralAddress.

Parameters
[in]referral_addressTarget referral address.
[out]dn_pReturned DN, which is suitable for passing to DS_BindSync_Strong, or NULL if none is available.
Return values
DS_E_BADPARAMEither referral_address or dn_p was NULL
DS_E_NOERRORA DS_DN was returned
Since
DSAPI_VERSION 2016
DS_Status DS_ReferralAddress_GetBindAddress ( const DS_ReferralAddress referral_address,
const char **  address_p 
)

Get the bind address from the given DS_ReferralAddress.

The returned value will be either a presentation address (RFC 1278 format), or an LDAP URL (RFC 2255 format) and will be suitable for using to create a new DS_Session.

Parameters
[in]referral_addressTarget referral address.
[out]address_pA null-terminated string containing the DSA's address, which is suitable for passing to DS_BindSync_Anonymous, DS_BindSync_Simple, or DS_BindSync_Strong.
Return values
DS_E_BADPARAMEither referral_address or dn_p was NULL
DS_E_NOERRORA DS_DN was returned
Since
DSAPI_VERSION 2016