CardCreateFile function

The CardCreateFile function creates a file on the card with a specified name and access permission. This function cannot be used to create directories. If the directory that is named by pszDirectoryName does not exist, the function fails with SCARD_E_DIR_NOT_FOUND.

Syntax

DWORD WINAPI CardCreateFile(
  _In_      PCARD_DATA                 pCardData,
  _Out_opt_ LPSTR                      pszDirectoryName,
  _In_      LPSTR                      pszFileName,
  _In_      DWORD                      cbInitialCreationSize,
  _In_      CARD_FILE_ACCESS_CONDITION AccessCondition
);

Parameters

• pCardData [in]
  Context information for the call. For more information, see CardAcquireContext.

• pszDirectoryName [out, optional]
  Name of the directory that is to contain the file. Set to NULL for root.

• pszFileName [in]
  Logical File Name for the file to be created.

• cbInitialCreationSize [in]
  Initial size of the file at creation time.

• AccessCondition [in]
  Access control permissions to be applied to the file.

Return value

Zero on success; otherwise, nonzero.

Remarks

The initial size parameter can be used to avoid the situation in which a later file write fails for lack of space after the file was successfully created. Rules for file name are as defined in ”File System Requirements” later in this specification.

If pszFileName is NULL or an empty string, an SCARD_E_INVALID_PARAMETER error must be returned. If cbInitialCreationSize is greater than the free space on the card, an SCARD_E_INVALID_PARAMETER error must be returned.

Currently-defined file access control permissions are taken from the CARD_FILE_ACCESS_CONDITION from Cardmod.h. The following are the file access control permissions:

• InvalidAc
• EveryoneReadUserWriteAc
• UserWriteExecuteAc
• EveryoneReadAdminWriteAc
• UserReadWriteAc
• AdminReadWriteAc

For more information about these control permissions for file access, see File System Requirements.

If CardCreateFile receives as a parameter the name of an existing file or directory (when creating a file in the root dir), it should fail with an ERROR_FILE_EXISTS error code.

If CardCreateFile is called on a nonexistent directory, an SCARD_E_DIR_NOT_FOUND error code must be returned.

If CardCreateFile is called on a file in a directory where the caller has no permissions to write, an SCARD_W_SECURITY_VIOLATION error code must be returned.

If the name that pszFileName or pszDirectoryName specified is longer than the maximum length for file/directory names, SCARD_E_INVALID_PARAMETER must be returned.

Requirements

Send comments about this topic to Microsoft