ePass1000 C/C++ API Reference Manual Version 2.0

# epas_OpenDevice

The epas_OpenDevice function finds and opens an ePass1000 for exclusive access, and create a session between application and device for further operation.

    EPAS_STATUS EPAS_API
    epas_OpenDevice(
        EPAS_HANDLE hContextHandle,    // [in]
        unsigned long ulFlags,         // [in]
        void* pAppID                   // [in]
    );

#### Requirement

epas_CreateContext

#### Parameters

hContextHandle
  [in] Handle to device context.
ulFlags
  [in]This parameter defines a bit mask of options for opening a device. You may use bit-wise OR operation to select more than one option. This parameter can be a combination of one or more of the following flags:

  Flag | Meaning
  --- | ---
  EPAS_OPEN_FIRST | Open the first found device. This flag can be combined with EPAS_OPEN_BY_NAME, EPAS_OPEN_BY_GUID or EPAS_OPEN_BY_GUID_STR.
  EPAS_OPEN_NEXT | Open the next device. This flag can be combined with EPAS_OPEN_BY_NAME, EPAS_OPEN_BY_GUID or EPAS_OPEN_BY_GUID_STR.
  EPAS_OPEN_CURRENT | Open the currently opened device. This flag can NOT be combined with other flags.
  EPAS_OPEN_SPECIFIC | Open the device, that has same serial number value as which specified by pAppID parameter. This flag can NOT be combined with other flags.
  EPAS_OPEN_BY_NAME | Open the device containing a directory name pointed to by pAppID. This parameter may be combined with EPAS_OPEN_FIRST or EPAS_OPEN_NEXT.
  EPAS_OPEN_BY_GUID | Open the device containing a directory GUID as specified by pAppID. This flag must combined with EPAS_OPEN_FIRST or EPAS_OPEN_NEXT.
  EPAS_OPEN_BY_GUID_STR | Open the device containing a directory GUID as specified by pAppID. This flag must combined with EPAS_OPEN_FIRST or EPAS_OPEN_NEXT.

pAppID
  [in]This optional parameter provide additional information for the open. This parameter is only used if one of the following flags is assigned. If none of the flags below are assigned, pAppID should be set to NULL.

  Flag | Meaning
  --- | ---
  EPAS_OPEN_SPECIFIC | pAppID point to an array of two unsigned longs which specified serial number of the device to be opened. Use epas_GetProperty method to obtain a device's serial number.
  EPAS_OPEN_BY_NAME | pAppID point to a NULL terminated string that specifies the Application Directory Name to open. If a device is opened, the current directory will be set to the directory ID defined by the Application Directory Name.
  EPAS_OPEN_BY_GUID | pAppID point to an array of 16 bytes that specified the Application Directory GUID to open. If a device is opened, the current directory will be set to the directory ID defined by the Application Directory GUID.
  EPAS_OPEN_BY_GUID_STR | pAppID point to a NULL terminated string that specifies the Application Directory GUID to open. If a device is opened, the current directory will be set to the directory ID defined by the Application Directory GUID. The string format is "{xxxxxxxx - xxxx - xxxx - xxxx - xxxxxxxxxxxx}". Dashes and braces are optional.

#### Remarks

The order of devices opened (first and next) is based on the order they were detected by the system. To enumerate all devices connected to the system, use EPAS_OPEN_FIRST and EPAS_OPEN_NEXT until FT_UNIT_NOT_FOUND is returned.

Application access to ePass1000 is exclusive. Only one application can open an ePass1000 at one time. If any other application attempt to open this ePass1000, will get return code FT_DEVICE_IN_USE.

You can open specific ePass1000 by combining EPAS_OPEN_FIRST, EPAS_OPEN_NEXT flags with EPAS_OPEN_BY_NAME , EPAS_OPEN_BY_GUID, or EPAS_OPEN_BY_GUID_STR.

If you known serial number of the ePass1000 you intend to open, use EPAS_OPEN_SPECIFIC.

#### Return Values

If the function succeeds, FT_SUCCESS returned.

If the library failed to open the device driver, FT_CANNOT_OPEN_DRIVER is returned.

If the library do not support version of the driver, FT_INVALID_DRVR_VERSION is returned.

If there is no device connected to the system currently, FT_UNIT_NOT_FOUND is returned.

If the device is already opened by another application, FT_DEVICE_IN_USE is returned.

For a list of all return codes, see Status Return Values.

#### Sample Code

    EPAS_STATUS epsRet;
    EPAS_HANDLE handle;

    epsRet = epas_OpenDevice(handle,EPAS_OPEN_FIRST,NULL);
    // If first device is in use, try next one.
    if (FT_DEVICE_IN_USE == epsRet)
    {
    	// Try and try...
    	while (1)
    	{
    		epsRet = epas_OpenDevice(handle,EPAS_OPEN_NEXT,NULL);
    		if (FT_DEVICE_IN_USE == epsRet)	continue;
    		break;
    	}
    }
    return epsRet;
    .
    .
    .

####

#### See Also

epas_CloseDevice