CardWriteFile function

The CardWriteFile function writes the entire contents of a data buffer to a file. The file contents are replaced, starting at the beginning of the file. The file must exist, or CardWriteFile fails.

Syntax

DWORD WINAPI CardWriteFile(
  _In_     PCARD_DATA pCardData,
  _In_opt_ LPSTR      pszDirectoryName,
  _In_     LPSTR      pszFileName,
  _In_     DWORD      dwFlags,
  _In_     DWORD      cbData,
  _In_     PBYTE      pbData
);

Parameters

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

• pszDirectoryName [in, optional]
  Name of the directory that contains the file. Set to NULL for root.

• pszFileName [in]
  Logical File Name for the file of interest.

• dwFlags [in]
  Reserved. Set to 0.

• cbData [in]
  Address of byte buffer that contains data to write to the file.

• pbData [in]
  Byte count of data to write to the file.

Return value

Zero on success; otherwise, nonzero.

Remarks

Rewriting the contents of an existing file presents special problems. If files change their allocated size, the available storage of the smart card can become fragmented. This results in significant loss of useful space. This is because it is usually infeasible to implement a reorganizing memory manager for card storage. Therefore, implementations can choose not to “shrink” a file if its size has been decreased.

Note  Users of this function should be careful not to rely on exact sizing of the file to its contents. The file size may exceed the data size.

If the size (cbData) that is specified through CardWriteFile is larger than the current file size that is specified through CardCreateFile, it should succeed, unless the card is out of space. If this is true, SCARD_E_WRITE_TOO_MANY should be returned.

Card minidriver-based cards must be able to dynamically grow files.

If incorrect flags are passed into dwFlags, the CardWriteFile call is expected to fail with the SCARD_E_INVALID_PARAMETER error code.

If pszFileName specifies a nonexistent file, CardWriteFile should fail with SCARD_E_FILE_NOT_FOUND.

If CardWriteFile is called on a nonexistent directory, an SCARD_E_DIR_NOT_FOUND 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