LDAP_REFERRAL_CALLBACK

The LDAP_REFERRAL_CALLBACK structure is used to implement external caching of connections.

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

Members

SizeOfCallbacks

Specifies the amount of memory needed 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. See the Remarks section following for more information.

NotifyRoutine

Pointer to a callback function that determines whether a newly created connection will be cached or destroyed after the operation has been completed. See Remarks for more information.

DereferenceRoutine

Pointer to a callback function to dereference a connection that is not in use. See the following Remarks section for more information.

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's 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 the callee doesn't want to cache the connection. When FALSE is returned, the connection will be destroyed once the operation is complete. The function should return TRUE if the callee has taken ownership of the connection and the connection will be cached. Note 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's 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 needed. 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.

Requirements

  Windows NT/2000: Requires Windows NT 4.0 SP4 or later.
  Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
  Header: Declared in Winldap.h.

See Also

Data Structures, ldap_set_option