ePass1000 C/C++ API Reference Manual Version 2.0

epas_CreateDir

The epas_CreateDir function creates a new directory under the current directory. Application must have proper right to create a directory.

EPAS_STATUS EPAS_API
epas_CreateDir(
    EPAS_HANDLE hContextHandle,      // [in]
    unsigned long ulFlags,           // [in]
    unsigned char* pucName,          // [in]
    unsigned char* pucGuid,          // [in]
    PEPAS_DIRINFO pDirInfo,          // [in][out]
    unsigned long ulSizeOfDirInfo    // [in]
);

Requirement

epas_CreateContext, epas_OpenDevice

Parameters

hContextHandle
[in] Handle to device context.
ulFlags
[in] A bit mast defines the options for directory creation. You may use OR operation to enable one or more option:
Flag Meaning
0 Create a directory ID as defined in the pDirInfo pointing structure.
EPAS_CREATE_AUTO_ID Create a directory with an automatically assigned ID. When this flag is set, the directory ulID in the pDirInfo parameter is ignored. Upon return, the ulID member of the pDirInfo parameter contains the automatically assigned ID.
EPAS_DIR_BY_GUID When this flag is set, the pucGuid parameter is a pointer to an array of 16 bytes defining the Application GUID of the directory.
EPAS_DIR_BY_GUID_STR When this flag is set, the pucGuid parameter is a pointer to an NULL terminated string defining the Application GUID.
EPAS_DIR_BY_NAME When this flag is set, the pucName parameter is a pointer to an NULL terminated string defining the Application Name.
pucName
[in] Pointer to a NULL terminated string that defines the Application Directory Name to the directory.

You can set NULL to ignore this parameter. Length of the Application Directory Name must in the range of 0 to EPAS_APP_NAME_SIZE - 1 bytes.

pucGuid
[in] Pointer to a buffer which contain the Application GUID to the directory.

When ulFlags is set to EPAS_DIR_BY_GUID, the buffer is an array of 16 byte GUID. When ulFlags is set to EPAS_DIR_BY_GUID_STR, the buffer is a NULL terminated string of GUID string. The format of the GUID string should be "{xxxxxxxx - xxxx - xxxx - xxxx - xxxxxxxxxxxx} ". Dashes and braces are optional. If neither EPAS_DIR_BY_GUID nor EPAS_DIR_BY_GUID_STR is defined, this parameter is ignored.

pDirInfo
[in][out] Pointer to an EPAS_DIRINFO structure that contains the information about the directory to be created.

If the directory is created successfully, the information of the directory is returned. You should first zero initialize this structure and set the proper fields before calling this function.

ulSizeOfDirInfo
[in] Size of the buffer pointed by the pDirInfo parameter.

Remarks

Applications should use Application Directory Name or Application Directory GUID to identify its directory instead of using directory IDs.

Devices can be opened using the Application Directory Name or GUID, see epas_OpenDevice.

Application Directory Name are global and case sensitive.

Application Directory GUID are global and duplications are not permitted.

Upon a successful creation of a directory, the current directory will be set to the newly created directory.

For a list of reserved directory IDs, see EPAS_DIRINFO.

Return Values

If the function succeeds, FT_SUCCESS returned.

If the directory creation access to the file has not granted, FT_ACCESS_DENIED returned.

If a directory with same ID, Name or GUID already exists, FT_ALREAD_EXISTS returned.

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

Sample Code

EPAS_STATUS epsRet;
EPAS_HANDLE handle;
EPAS_DIRINFO di;
epsRet = epas_CreateDir(handle,
                        EPAS_CREATE_AUTO_ID | EPAS_DIR_BY_GUID,
                        APP_NAME,
                        (unsigned char*)&guid,
                        &di,
                        sizeof(EPAS_DIRINFO)
                        );
.
.
.

See Also

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