CardRegisterClient

The CardRegisterClient function registers a callback function that is called by Card Services when a specified socket event occurs. The callback function notifies the driver of the event, such as card insertion, so the driver can take the appropriate action.

Syntax

CARD_CLIENT_HANDLE CardRegisterClient(
CLIENT_CALLBACK CallBackFn PCARD_REGISTER_PARMS pParms );

Parameters

CallBackFn: Specifies a pointer to the driver's callback function.
pParms: Specifies a pointer to a CARD_REGISTER_PARMS structure defining the drivers characteristics.

Return Values

If successful, CardRegisterClient returns a driver handle. If unsuccessful, it returns NULL and GetLastError returns one of the following values:

Value	Description
CERR_BAD_ARGS	Indicates the pointer specified in pParms or CallBackFn is invalid.
CERR_OUT_OF_RESOURCE	Indicates Card Services is unable to allocate memory to track the driver.

Remarks

A driver can request artificial insertion notifications so it can check whether a card it controls has already been inserted.

Card Services sends a CE_CARD_INSERTION callback event code for every function on the PC Cards that are currently inserted. If the driver does not want to receive these artificial insertion notices, it can clear the CLIENT_ATTR_NOTIFY_SHARED and CLIENT_ATTR_NOTIFY_EXCLUSIVE bits in the fAttributes field of the CARD_REGISTER_PARMS structure.

Because the CE_CARD_INSERTION callbacks can occur before CardRegisterClient returns, the Parm2 member of the CARD_EVENT_PARMS structure contains the registering client's CARD_CLIENT_HANDLE. For the same reason, Parm1 also contains the registering client's handle on the CE_REGISTRATION_COMPLETE callback.

When the driver is unloaded, it must call CardDeregisterClient to free any PC Card resources allocated to the driver.