ePass1000 C/C++ API Reference Manual Version 2.0

# epas_ChangeDir

The epas_ChangeDir function changes the current directory.

    EPAS_STATUS EPAS_API
    epas_ChangeDir(
        EPAS_HANDLE hContextHandle,       // [in]
        unsigned long ulFlags,            // [in]
        unsigned long ulDirID,            // [in]
        unsigned char* pucDirName         // [in]
    );

#### Requirement

epas_CreateContext, epas_OpenDevice

#### Parameters

hContextHandle
  [in] Handle to device context.
ulFlags
  [in] A bit mask defining the options for directory. changing. You may use OR operation to enable one or more options :

  Flag | Meaning
  --- | ---
  EPAS_DIR_BY_ID | When this flag is set, ulDirID parameter contain ID of the directory to be changed into. This flag may be combined with EPAS_DIR_FROM_MF or EPAS_DIR_FROM_CUR_DF. ulDirID must be a 16-bit directory ID.
  EPAS_DIR_BY_LONG_ID | When this flag is set, ulDirID parameter contain ID of the directory to be changed into. This flag may be combined with EPAS_DIR_FROM_MF or EPAS_DIR_FROM_CUR_DF.
  EPAS_DIR_BY_NAME | When this flag is set, pucDirName parameter contain Application Name of the directory to be changed into. This flag cannot combine with others.
  EPAS_DIR_BY_GUID | When this flag is set, pucDirName parameter contain Application GUID of the directory to be changed into. This flag cannot combine with others.
  EPAS_DIR_BY_GUID_STR | When this flag is set, pucDirName parameter contain Application GUID string of the directory to be changed into. This flag cannot combine with others.

  Additionally, one of the following flags can be used to specify the relative location:

  Flag | Meaning
  --- | ---
  EPAS_DIR_FROM_MF | Change relative to root directory (Master File). This is the default option.
  EPAS_DIR_FROM_CUR_DF | Change relative to current directory.
  EPAS_DIR_TO_PARENT | Change to the parent directory of the current directory. This flag cannot be combined with others, ulDirID and pucDirName are ignored.

ulDirID
  [in] ID of the directory to change to. This parameter is only valid when one of the following flags is set:

  Flag | Meaning
  --- | ---
  EPAS_DIR_BY_ID | ulDirID contain a 16-bit directory ID in the range of 0 to 0xEFFF.
  EPAS_DIR_BY_LONG_ID | ulDirID contain a 32-bit directory ID in the range of 0 to 0xFFFFFFFF.

  If none of these flags are specified, then the ulDirID parameter should be set to NULL.

  The ulDirID parameter is ignored if EPAS_DIR_TO_PARENT is set.

pucDirName
  [in] Application Name or GUID of the directory to change to. This parameter is only valid when one of the following flags is set:

  Flag | Meaning
  --- | ---
  EPAS_DIR_BY_NAME | Pointer to a NULL terminated string that is the Application Name assigned to the directory. Application Directory Name are case sensitive and global. Duplicates are not allowed.
  EPAS_DIR_BY_GUID | Pointer to an array of 16 bytes that is the Application Directory GUID assigned to the directory. Application Directory GUID are global and duplicates are not allowed.
  EPAS_DIR_BY_GUID_STR | Pointer to a NULL terminated string that is the Application Directory GUID assigned to the directory. The GUID string format is "{xxxxxxxx- xxxx - xxxx - xxxx - xxxxxxxxxxxx}". Application Directory GUID strings are global and duplicates are not allowed.

#### Remarks

You may assign the Application Directory Name and GUID when use epas_CreateDir function to create the directory.

You may use the epas_GetProperty function to retrieve the access setting of a directory.

You may use the epas_GetProperty function to retrieve the Application Name or GUID of a directory.

To change to the root directory (Master File), use the directory ID of EPAS_ROOT_DIR with the flag EPAS_DIR_BY_ID.

For a list of reserved directory IDs, see EPAS_DIRINFO.

#### Return Values

If the function succeeds, FT_SUCCESS returned.

If the specified directory not found, FT_DIR_NOT_FOUND returned.

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

#### See Also

epas_CreateFile, epas_DeleteFile, epas_OpenFile, epas_CloseFile, epas_GetFileInfo, epas_Read, epas_Write, epas_CreateDir, epas_DeleteDir, epas_GetCurrentDir, epas_Directory