Directory Services

LDAP_REFERRAL_CALLBACK

The LDAP_REFERRAL_CALLBACK structure is used to implement external caching of connections. This structure is used only when tracking referrals.

typedef struct LdapReferralCallback {
ULONG SizeOfCallbacks;
QUERYFORCONNECTION* QueryForConnection;
NOTIFYOFNEWCONNECTION* NotifyRoutine;
DEREFERENCECONNECTION* DereferenceRoutine; } LDAP_REFERRAL_CALLBACK,
*PLDAP_REFERRAL_CALLBACK;

Members

SizeOfCallbacks
Specifies the amount of memory required for the callback mechanism. Set this field to sizeof(LDAP_REFERRAL_CALLBACK).
QueryForConnection
Pointer to a callback function to determine whether there is a cached connection cached available. For more information, see the Remarks section.
NotifyRoutine
Pointer to a callback function that determines whether a new connection will be cached or destroyed after the operation completes. For more information, see the Remarks section.
DereferenceRoutine
Pointer to a callback function to dereference a connection that is not in use. For more information, see the Remarks section.

Remarks

Use the LDAP_REFERRAL_CALLBACK structure to implement a mechanism for caching connections. The structure contains three callback functions which you implement in your client code.

QUERYFORCONNECTION: If a connection is available, this function should return a pointer to the connection to use in ConnectionToUse. If no connection is available, the function should set ConnectionToUse to NULL. The signature for this callback function is as follows.

typedef ULONG (_cdecl QUERYFORCONNECTION)(
	PLDAP	 PrimaryConnection,
	PLDAP	 ReferralFromConnection,
	PWCHAR	NewDN,
	PCHAR	 HostName,
	ULONG	 PortNumber,
	PVOID	 SecAuthIdentity, // If NULL, use CurrentUser below
	PVOID	 CurrentUserToken,   // pointer to current user LUID.
	PLDAP	 *ConnectionToUse
);

NOTIFYOFNEWCONNECTION: The run time calls this function if a new connection was created in the course of chasing a referral. This function should return FALSE if not required to cache the connection. When FALSE is returned, the connection is destroyed when the operation completes. The function should return TRUE if it has taken ownership of the connection and the connection will be cached. Be aware that any new connections so created inherit the current callbacks from the primary connection on which the request was initiated. The signature for this function is.

typedef BOOLEAN (_cdecl NOTIFYOFNEWCONNECTION) 
	(
	PLDAP	 PrimaryConnection,
	PLDAP	 ReferralFromConnection,
	PWCHAR	NewDN,
	PCHAR	 HostName,
	PLDAP	 NewConnection,
	ULONG	 PortNumber,
	PVOID	 SecAuthIdentity, // If null, use CurrentUser below.
	PVOID	 CurrentUser, 	// Pointer to current user LUID.
	ULONG	 ErrorCodeFromBind   // If non-zero, bind to server failed.
	);

DEREFERENCECONNECTION: The LDAP run time calls this function to dereference a connection that is no longer required. The connection may have come from a successful call to QueryForConnection or from NotifyOfNewConnection. The function should return LDAP_SUCCESS if the call succeeds; currently, however, the run time ignores the return value. The signature for this function is as follows.

typedef ULONG (_cdecl DEREFERENCECONNECTION)
	(
	PLDAP	 PrimaryConnection,
	PLDAP	 ConnectionToDereference
	);

To configure a session to use callbacks to obtain a cached connection, call ldap_set_option( conn, LDAP_OPT_REFERRAL_CALLBACK, &referralRoutines ), where referralRoutines is the address of the LDAP_REFERRAL_CALLBACK structure that contains your routines. The addresses may be NULL, in which case the LDAP run time will not make the calls.

The parameter descriptions for the preceding three functions are as follows:

Requirements

Client: Included in Windows XP and Windows 2000 Professional.
Server: Included in Windows Server 2003 and Windows 2000 Server.
Redistributable: Requires Active Directory Client Extension on Windows NT 4.0 SP6a and Windows 95/98/Me.
Header: Declared in Winldap.h.

See Also

Data Structures, ldap_set_option