SCardEstablishContext function (winscard.h)

Article
10/13/2021

The SCardEstablishContext function establishes the resource manager context (the scope) within which database operations are performed.

Syntax

LONG SCardEstablishContext(
  [in]  DWORD          dwScope,
  [in]  LPCVOID        pvReserved1,
  [in]  LPCVOID        pvReserved2,
  [out] LPSCARDCONTEXT phContext
);

Parameters

[in] dwScope

Scope of the resource manager context. This parameter can be one of the following values.

Value	Meaning
SCARD_SCOPE_USER	Database operations are performed within the domain of the user.
SCARD_SCOPE_SYSTEM	Database operations are performed within the domain of the system. The calling application must have appropriate access permissions for any database actions.

[in] pvReserved1

Reserved for future use and must be NULL. This parameter will allow a suitably privileged management application to act on behalf of another user.

[in] pvReserved2

Reserved for future use and must be NULL.

[out] phContext

A handle to the established resource manager context. This handle can now be supplied to other functions attempting to do work within this context.

Return value

If the function succeeds, the function returns SCARD_S_SUCCESS.

If the function fails, it returns an error code. For more information, see Smart Card Return Values.

Remarks

The context handle returned by SCardEstablishContext can be used by database query and management functions. For more information, see Smart Card Database Query Functions and Smart Card Database Management Functions.

To release an established resource manager context, use SCardReleaseContext.

If the client attempts a smart card operation in a remote session, such as a client session running on a terminal server, and the operating system in use does not support smart card redirection, this function returns ERROR_BROKEN_PIPE.

Examples

The following example establishes a resource manager context.

SCARDCONTEXT    hSC;
LONG            lReturn;
// Establish the context.
lReturn = SCardEstablishContext(SCARD_SCOPE_USER,
                                NULL,
                                NULL,
                                &hSC);
if ( SCARD_S_SUCCESS != lReturn )
    printf("Failed SCardEstablishContext\n");
else
{
    // Use the context as needed. When done,
    // free the context by calling SCardReleaseContext.
    // ...
}

Requirements

Requirement	Value
Minimum supported client	Windows XP [desktop apps only]
Minimum supported server	Windows Server 2003 [desktop apps only]
Target Platform	Windows
Header	winscard.h
Library	Winscard.lib
DLL	Winscard.dll

Share via