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. More...

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. More...

const DS_Referral *	DS_Referral_GetNext (const DS_Referral *referral)
	Get the next referral or continuation reference (if any) in a list of referrals. More...

const DS_ReferralAddress *	DS_Referral_GetFirstAddress (const DS_Referral *referral)
	Get the first referral address from a DS_Referral. More...

const DS_ReferralAddress *	DS_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

◆ DS_ReferralList_GetFirst()

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_list source referral list.

Return values

NULL	If there are no referrals in the list
non-NULL	Pointer to the first referral in the list

Since: DSAPI_VERSION 2016

◆ DS_Referral_GetNext()

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] referral current referral in the list.

Return values

NULL	If there are no more referrals in the list
non-NULL	Pointer to the next referral in the list

Since: DSAPI_VERSION 2016

◆ DS_Referral_GetFirstAddress()

const DS_ReferralAddress* DS_Referral_GetFirstAddress ( const DS_Referral * referral )

Get the first referral address from a DS_Referral.

Parameters

[in] referral a DS_Referral.

Return values

a	pointer to the first DS_ReferralAddress in the list

Since: DSAPI_VERSION 2016

◆ DS_ReferralAddress_GetNext()

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_address current address in the list.

Return values

NULL	If there are no more referral addresses in the list
non-NULL	Pointer to the next referral address in the list

Since: DSAPI_VERSION 2016

◆ DS_Referral_GetTargetDN()

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]	referral	Target referral.
[out]	dn_p	A 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_BADPARAM	Either referral or dn_p was NULL
DS_E_NOERROR	A DS_DN was returned

Since: DSAPI_VERSION 2016

◆ DS_ReferralAddress_GetDSADN()

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_address	Target referral address.
[out]	dn_p	Returned DN, which is suitable for passing to DS_BindSync_Strong, or NULL if none is available.

Return values

DS_E_BADPARAM	Either referral_address or dn_p was NULL
DS_E_NOERROR	A DS_DN was returned

Since: DSAPI_VERSION 2016

◆ DS_ReferralAddress_GetBindAddress()

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_address	Target referral address.
[out]	address_p	A 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_BADPARAM	Either referral_address or dn_p was NULL
DS_E_NOERROR	A DS_DN was returned

Since: DSAPI_VERSION 2016