pcsc-sharp : PCSC Namespace

SCardContext Class

Manages an Application Context to the PC/SC Resource Manager.

public class SCardContext : IDisposable

Remarks

Requirements

Namespace: PCSC
Assembly: pcsc-sharp (in pcsc-sharp.dll)
Assembly Versions: 1.0.0.0, 2.0.0.0, 2.0.0.1

Members

See Also: Inherited members from object.

Public Constructors

Creates a new SCardContext object.

Public Fields

const
Infinite IntPtr (4294967295). Infinite timeout.

Public Properties

[read-only]
Handle IntPtr . A pointer (Application Context) that can be used for C API calls.
[read-only]
static
Infinite IntPtr . Infinite timeout (const. value).
[read-only]
static
MaxATRSize int . Maximum ATR size.

Public Methods

Cancel () : SCardError
Cancels all pending blocking requests on the SCardContext.GetStatusChange(IntPtr, SCardReaderState[]) method.
CheckValidity () : SCardError
Checks the validity of the current context.
Dispose ()
Disposes a PC/SC context.
Establish (SCardScope)
Creates an Application Context to the PC/SC Resource Manager.
Finalize ()
GetReaderGroups () : string[]
Returns a list of currently available reader groups on the system.
GetReaders () : string[]
Returns a list of currently available readers on the system.
GetReaders (string[]) : string[]
Returns a list of currently available readers on the system.
GetReaderStatus (string) : SCardReaderState
Returns the current reader status.
GetReaderStatus (string[]) : SCardReaderState[]
Returns the current reader status of all requested readers.
GetStatusChange (IntPtr, SCardReaderState[]) : SCardError
Blocks execution until the current availability of the cards in a specific set of readers changes.
IsValid () : bool
Checks the validity of the current context.
ReEstablish ()
Re-Establishes an Application Context to the PC/SC Resource Manager with the last used PCSC.SCardScope.
Release ()
Destroys a communication context to the PC/SC Resource Manager.

Member Details

SCardContext Constructor

Creates a new SCardContext object.

public SCardContext ()

Remarks

Each thread of an application shall use its own SCardContext.

Requirements

Namespace: PCSC
Assembly: pcsc-sharp (in pcsc-sharp.dll)
Assembly Versions: 1.0.0.0, 2.0.0.0, 2.0.0.1

Cancel Method

Cancels all pending blocking requests on the SCardContext.GetStatusChange(IntPtr, SCardReaderState[]) method.

public SCardError Cancel ()

Returns

Return value Description
SCardError.Success Successful (SCARD_S_SUCCESS)
SCardError.InvalidHandle Invalid context (SCARD_E_INVALID_HANDLE)
SCardError.NoService Server is not running (SCARD_E_NO_SERVICE)
SCardError.CommunicationError An internal communications error has been detected (SCARD_F_COMM_ERROR)

Remarks

This method calls the API function SCardCancel().

Requirements

Namespace: PCSC
Assembly: pcsc-sharp (in pcsc-sharp.dll)
Assembly Versions: 1.0.0.0, 2.0.0.0, 2.0.0.1

CheckValidity Method

Checks the validity of the current context.

public SCardError CheckValidity ()

Returns

Return value Description
SCardError.Success The context is valid. (SCARD_S_SUCCESS)
SCardError.InvalidHandle The context is invalid. (SCARD_E_INVALID_HANDLE)

Remarks

Call this function to determine whether a smart card context handle is still valid. After a smart card context handle has been set by SCardContext.Establish(SCardScope), it may become not valid if the resource manager service has been shut down.

This method calls the API function SCardIsValidContext().

Requirements

Namespace: PCSC
Assembly: pcsc-sharp (in pcsc-sharp.dll)
Assembly Versions: 1.0.0.0, 2.0.0.0, 2.0.0.1

Dispose Method

Disposes a PC/SC context.

public void Dispose ()

Remarks

If a context to the PC/SC Resource Manager is established, Dispose() will call the SCardContext.Release() method silently.

Requirements

Namespace: PCSC
Assembly: pcsc-sharp (in pcsc-sharp.dll)
Assembly Versions: 1.0.0.0, 2.0.0.0, 2.0.0.1

Establish Method

Creates an Application Context to the PC/SC Resource Manager.

public void Establish (SCardScope scope)

Parameters

scope
Scope of the establishment. This can either be a local or remote connection.

Remarks

Creates an Application Context for a client. This must be the first WinSCard function called in a PC/SC application. Each thread of an application shall use its own PCSC.SCardContext.

This method calls the API function SCardEstablishContext().

C# Example
SCardContext context = new SCardContext();
context.Establish(SCardScope.System);
  

Requirements

Namespace: PCSC
Assembly: pcsc-sharp (in pcsc-sharp.dll)
Assembly Versions: 1.0.0.0, 2.0.0.0, 2.0.0.1

Finalize Method

void Finalize ()

Remarks

Documentation for this section has not yet been entered.

Requirements

Namespace: PCSC
Assembly: pcsc-sharp (in pcsc-sharp.dll)
Assembly Versions: 1.0.0.0, 2.0.0.0, 2.0.0.1

GetReaderGroups Method

Returns a list of currently available reader groups on the system.

public string[] GetReaderGroups ()

Returns

An array of strings containing all Smart Card reader groups found by the PC/SC Resource Manager.

Remarks

This method calls the API function SCardListReaderGroups().

C# Example
SCardContext context = new SCardContext();
context.Establish(SCardScope.System);

// list all configured reader groups
Console.Out.WriteLine("\nCurrently configured readers groups: ");
string[] groups = context.GetReaderGroups();
foreach (string group in groups)
	Console.WriteLine("\t" + group);

context.Release();
  

Requirements

Namespace: PCSC
Assembly: pcsc-sharp (in pcsc-sharp.dll)
Assembly Versions: 1.0.0.0, 2.0.0.0, 2.0.0.1

GetReaders Method

Returns a list of currently available readers on the system.

public string[] GetReaders ()

Returns

An array of strings containing all Smart Card readers found by the PC/SC Resource Manager.

Remarks

This method calls the API function SCardListReaders().

C# Example
SCardContext context = new SCardContext();
context.Establish(SCardScope.System);

// list all (smart card) readers
Console.Out.WriteLine("Currently connected readers: ");
string[] readers = context.GetReaders();
foreach (string reader in readers)
	Console.WriteLine("\t" + reader);

context.Release();
  

Requirements

Namespace: PCSC
Assembly: pcsc-sharp (in pcsc-sharp.dll)
Assembly Versions: 1.0.0.0, 2.0.0.0, 2.0.0.1

GetReaders Method

Returns a list of currently available readers on the system.

public string[] GetReaders (string[] Groups)

Parameters

Groups
List of groups to list readers.

Returns

An array of strings containing all Smart Card readers found by the PC/SC Resource Manager.

Remarks

Groups is not used on Linux/UNIX machines using the PC/SC Lite daemon.

This method calls the API function SCardListReaders().

C# Example
SCardContext context = new SCardContext();
context.Establish(SCardScope.System);

// list all configured reader groups
Console.Out.WriteLine("\nCurrently configured readers groups: ");
string[] groups = context.GetReaderGroups();
foreach (string group in groups)
	Console.WriteLine("\t" + group);

// list readers for each group
foreach (string group in groups)
{
	Console.WriteLine("\nGroup " + group + " contains ");
	foreach (string reader in context.GetReaders(new string[] {group}))
		Console.WriteLine("\t" + reader);
}

context.Release();
  

Requirements

Namespace: PCSC
Assembly: pcsc-sharp (in pcsc-sharp.dll)
Assembly Versions: 1.0.0.0, 2.0.0.0, 2.0.0.1

GetReaderStatus Method

Returns the current reader status.

public SCardReaderState GetReaderStatus (string readername)

Parameters

readername
The requested reader.

Returns

A PCSC.SCardReaderState that contains the current reader status.

Remarks

This method uses the SCardContext.GetStatusChange(IntPtr, SCardReaderState[]) method with a timeout of zero.

C# Example
// Helper function to display the ATR
static string StringAtr(byte[] atr)
{
	if (atr == null)
		return null;

	StringBuilder sb = new StringBuilder();
	foreach (byte b in atr)
		sb.AppendFormat("{0:X2}", b);

	return sb.ToString();
}
  
C# Example
// Retrieve the names of all installed readers.
SCardContext ctx = new SCardContext();
ctx.Establish(SCardScope.System);
string[] readernames = ctx.GetReaders();

// Get the current status of the first reader in "readernames".
SCardReaderState state = ctx.GetReaderStatus(readernames[0]);

Console.WriteLine("Reader: " + state.ReaderName);
Console.WriteLine("CurrentState: " + state.CurrentState 
	+ " EventState: " + state.EventState + "\n"
	+ "CurrentStateValue: " + state.CurrentStateValue 
	+ " EventStateValue: " + state.EventStateValue);
Console.WriteLine("UserData: " + state.UserData.ToString()
	+ " CardChangeEventCnt: " + state.CardChangeEventCnt);
Console.WriteLine("ATR: " + StringAtr(state.ATR));
            
ctx.Release();
  

Requirements

Namespace: PCSC
Assembly: pcsc-sharp (in pcsc-sharp.dll)
Assembly Versions: 1.0.0.0, 2.0.0.0, 2.0.0.1

GetReaderStatus Method

Returns the current reader status of all requested readers.

public SCardReaderState[] GetReaderStatus (string[] readernames)

Parameters

readernames
Requested reader names.

Returns

An array of PCSC.SCardReaderStates that contains the current reader status of each requested reader.

Remarks

This method uses the SCardContext.GetStatusChange(IntPtr, SCardReaderState[]) method with a timeout of zero.

C# Example
// Helper function to display the ATR.
static string StringAtr(byte[] atr)
{
	if (atr == null)
		return null;

	StringBuilder sb = new StringBuilder();
	foreach (byte b in atr)
		sb.AppendFormat("{0:X2}", b);

	return sb.ToString();
}
  
C# Example
// Retrieve the names of all installed readers.
SCardContext ctx = new SCardContext();
ctx.Establish(SCardScope.System);
string[] readernames = ctx.GetReaders();

// Get the current status of each reader in "readernames".
SCardReaderState[] states = ctx.GetReaderStatus(readernames);

foreach (SCardReaderState state in states)
{
	Console.WriteLine(">>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>");
	Console.WriteLine("Reader: " + state.ReaderName);
	Console.WriteLine("CurrentState: " + state.CurrentState 
		+ " EventState: " + state.EventState + "\n"
		+ "CurrentStateValue: " + state.CurrentStateValue 
		+ " EventStateValue: " + state.EventStateValue);
	Console.WriteLine("UserData: " + state.UserData.ToString()
		+ " CardChangeEventCnt: " + state.CardChangeEventCnt);
	Console.WriteLine("ATR: " + StringAtr(state.ATR));
}
            
ctx.Release();
  

Requirements

Namespace: PCSC
Assembly: pcsc-sharp (in pcsc-sharp.dll)
Assembly Versions: 1.0.0.0, 2.0.0.0, 2.0.0.1

GetStatusChange Method

Blocks execution until the current availability of the cards in a specific set of readers changes.

public SCardError GetStatusChange (IntPtr timeout, SCardReaderState[] readerstates)

Parameters

timeout
Maximum waiting time (in milliseconds) for status change, zero or SCardContext.Infinite for infinite.
readerstates
Structures of readers with current states.

Returns

A PCSC.SCardError indicating an error or the success.The caller receives status changes through the PCSC.SCardReaderState array.

Return value Description
SCardError.Success Successful (SCARD_S_SUCCESS)
SCardError.NoService Server is not running (SCARD_E_NO_SERVICE)
SCardError.InvalidParameter readerstates is invalid or null (SCARD_E_INVALID_PARAMETER)
SCardError.InvalidValue Invalid States, reader name, etc (SCARD_E_INVALID_VALUE)
SCardError.InvalidHandle Invalid context (SCARD_E_INVALID_HANDLE)
SCardError.ReaderUnavailable The reader is unavailable (SCARD_E_READER_UNAVAILABLE)
SCardError.Timeout The user-specified timeout value has expired (SCARD_E_TIMEOUT)

Remarks

This method receives a structure or list of structures containing reader names. It then blocks for a change in state to occur for a maximum blocking time of timeout or forever if SCardContext.Infinite is used.

The new event state will be contained in SCardReaderState.EventState. A status change might be a card insertion or removal event, a change in ATR, etc.

To wait for a reader event (reader added or removed) you may use the special reader name "\\?PnP?\Notification". If a reader event occurs the state of this reader will change and the bit SCRState.Changed will be set.

This method calls the API function SCardGetStatusChange().

Requirements

Namespace: PCSC
Assembly: pcsc-sharp (in pcsc-sharp.dll)
Assembly Versions: 1.0.0.0, 2.0.0.0, 2.0.0.1

Handle Property

A pointer (Application Context) that can be used for C API calls.

public IntPtr Handle { get; }

Value

The returned Application Context handle. Is 0 if not context has been established.

Remarks

This is the Application Context handle that is returned when calling the C API function SCardEstablishContext().

Requirements

Namespace: PCSC
Assembly: pcsc-sharp (in pcsc-sharp.dll)
Assembly Versions: 1.0.0.0, 2.0.0.0, 2.0.0.1

Infinite Field

Infinite timeout.

Value: 4294967295

public const IntPtr Infinite

Remarks

Requirements

Namespace: PCSC
Assembly: pcsc-sharp (in pcsc-sharp.dll)
Assembly Versions: 1.0.0.0

Infinite Property

Infinite timeout (const. value).

public static IntPtr Infinite { get; }

Value

Remarks

Requirements

Namespace: PCSC
Assembly: pcsc-sharp (in pcsc-sharp.dll)
Assembly Versions: 2.0.0.0, 2.0.0.1

IsValid Method

Checks the validity of the current context.

public bool IsValid ()

Returns

true if the context is valid.

Remarks

Call this function to determine whether a smart card context handle is still valid. After a smart card context handle has been set by SCardContext.Establish(SCardScope), it may become not valid if the resource manager service has been shut down.

C# Example
SCardContext context = new SCardContext();
context.Establish(SCardScope.System);

Console.Out.WriteLine("Context is valid? -> " + context.IsValid());

context.Release();
  

Requirements

Namespace: PCSC
Assembly: pcsc-sharp (in pcsc-sharp.dll)
Assembly Versions: 1.0.0.0, 2.0.0.0, 2.0.0.1

MaxATRSize Property

Maximum ATR size.

public static int MaxATRSize { get; }

Value

Platform MaxATRSize
Windows (Winscard.dll) 36
UNIX/Linux (PC/SClite) 33

Remarks

Attention: Size depends on platform.

Requirements

Namespace: PCSC
Assembly: pcsc-sharp (in pcsc-sharp.dll)
Assembly Versions: 1.0.0.0, 2.0.0.0, 2.0.0.1

ReEstablish Method

Re-Establishes an Application Context to the PC/SC Resource Manager with the last used PCSC.SCardScope.

public void ReEstablish ()

Remarks

This method must not be called before SCardContext.Establish(SCardScope)

Requirements

Namespace: PCSC
Assembly: pcsc-sharp (in pcsc-sharp.dll)
Assembly Versions: 1.0.0.0, 2.0.0.0, 2.0.0.1

Release Method

Destroys a communication context to the PC/SC Resource Manager.

public void Release ()

Remarks

This must be the last method called in a PC/SC application.

This method calls the API function SCardReleaseContext().

C# Example
SCardContext context = new SCardContext();

// establish context
context.Establish(SCardScope.System);
// release context
context.Release();
  

Requirements

Namespace: PCSC
Assembly: pcsc-sharp (in pcsc-sharp.dll)
Assembly Versions: 1.0.0.0, 2.0.0.0, 2.0.0.1