File Transfer Services

Introduction

The STRIDE Framework provides an API for performing file operations on the host from test code executing on the device. In order for the file APIs to be operational, your test code must be executed in the context of the STRIDE Runner. The host filesystem operations provided by this APIs encompass the following functionality:

• open/close
• read/write
• seek/tell
• tempfile name creation
• move/deletion
• error messaging related to any failures in these operations

Examples

read entire contents of a host file

The following code sample shows how to read the entire contents of a file on the host. The code currently just discards the buffer contents with each read operation, but actual code would likely store or process the file contents.

srCHAR file[] = "/path/to/host/file";
srBYTE readBuffer[srFILE_DATA_CHUNK_SIZE] = {0};
srFileHandle_t handle = 0;
srDWORD result = 0;
srDWORD totalBytesRead = 0;

/* open host file */
if (0 != (result = srFileOpen(file , "r", &handle)))
  goto QUIT;

while (srFALSE == srFileEOF(handle))
{
  srDWORD actualBytesRead = 0;
  if (0 != (result = srFileRead(handle, readBuffer, srFILE_DATA_CHUNK_SIZE, &actualBytesRead)))
    goto QUIT;

  totalBytesRead += actualBytesRead;
  /* TODO - do something with the contents of the readBuffer */
}

srLOG2_INFO("read %lu bytes from %s", totalBytesRead , file);

QUIT:
if (result != 0)
{
  srCHAR errorBuffer[srFILE_MAX_ERROR_LENGTH] = {0};
  srFileGetErrorMessage(result, errorBuffer, srFILE_MAX_ERROR_LENGTH);
  srLOG_ERROR(errorBuffer);
}
  
if (handle !=0)
  srFileClose(handle);

Reference

The following sections document the srFile API.

srFileOpen

srFileOpen() opens a file on the host computer.

srDWORD srTestPointExpect(const srCHAR * szHostPath, 
                          const srCHAR * szMode,
                          srFileHandle_t * phFile);

Parameters	Type	Description
szHostPath	Input	Full path to the remote file (located on the host computer)
szMode	Input	Mode string for opening the file - can be one of the following: r w a A '+' sign can be added to any of these mode characters to request simultaneous read/write access. Files are always opened in binary mode, so no text character translation is done.
phFile	Output	Pointer to store a handle to be used to specify this file in subsequent operations

Return Value	Description
srDWORD	0 on success, error code otherwise.

srFileClose

srFileClose () closes a remote file associated with the specified handle.

srDWORD srFileClose(srFileHandle_t hFile);

Parameters	Type	Description
hFile	Input	Handle specifying an open file stream

Return Value	Description
srDWORD	0 on success, error code otherwise.

srFileSeek

srFileSeek() seeks to the specified position within an open remote file stream by moving lOffset bytes relative to a position specified by eOrigin.

srDWORD srFileSeek(srFileHandle_t hFile, 
                   srLONG lOffset, 
                   srFileSeekOrigin_e eOrigin);

Parameters	Type	Description
hFile	Input	Handle specifying an open file stream
lOffset	Input	Number of bytes to offset from eOrigin
eOrigin	Input	Position to which lOffset is added. It is specified by one of the following enumerations: srSEEK_BEGIN srSEEK_CUR srSEEL_END

Return Value	Description
srDWORD	0 on success, error code otherwise.

srFileTell

srFileTell() returns the current position of hFile relative to the beginning of the file.

srDWORD srFileTell(srFileHandle_t hFile, 
                   srLONG* plOffset);

Parameters	Type	Description
hFile	Input	Handle specifying an open file stream
plOffset	Input	Pointer to store the current position in the file

Return Value	Description
srDWORD	0 on success, error code otherwise.

srFileRead

srFileRead() reads dwBytesToRead bytes from an open remote file stream and stores the data in the memory pointed to by pvData. The current position of the stream is advanced by the number of bytes read.

srDWORD srFileRead(srFileHandle_t hFile, 
                   void * pvData, 
                   srDWORD dwBytesToRead, 
                   srDWORD * pdwBytesRead);

Parameters	Type	Description
hFile	Input	Handle specifying an open file stream
pvData	Output	Pointer to a block of memory with a minimum size of dwBytesToRead bytes
dwBytesToRead	Input	Number of bytes to be read
pdwBytesRead	Output	Pointer to store the number of bytes successfully read. If this number differs from dwBytesToRead either an error has occurred or the end-of-file was reached.

Return Value	Description
srDWORD	0 on success, error code otherwise.

srFileWrite

srFileWrite() writes dwBytesToWrite bytes from the memory location specified in pvData to an open remote file stream. The current position of the stream is advanced by the number of bytes written.

srDWORD srFileWrite(srFileHandle_t hFile, 
                    const void * pvData,
                    srDWORD dwBytesToWrite, 
                    srDWORD * pdwBytesWritten);

Parameters	Type	Description
hFile	Input	Handle specifying an open file stream
pvData	Input	Pointer to a block of memory to read from - must contain dwBytesToWrite bytes of data.
dwBytesToWrite	Input	Number of bytes to be written
pdwBytesWritten	Output	Pointer to store the number of bytes successfully written. If this number differs from dwBytesToWrite an error has occurred.

Return Value	Description
srDWORD	0 on success, error code otherwise.

srFileEOF

srFileEOF() checks whether the remote file's end of file flag is set.

srBOOL srFileEOF(srFileHandle_t hFile);

Parameters	Type	Description
hFile	Input	Handle specifying an open file stream

Return Value	Description
srBOOL	srTRUE if the EOF flag is set for the remote file, srFALSE otherwise.

srFileError

srFileError() checks whether the remote file error flag has been set by a preceeding operation.

srBOOL srFileError(srFileHandle_t hFile);

Parameters	Type	Description
hFile	Input	Handle specifying an open file stream

Return Value	Description
srBOOL	srTRUE if the error flag is set for the remote file, srFALSE otherwise.

srFileClearErr

srFileClearErr() clears the error flag for the remote file

void srFileClearErr(srFileHandle_t hFile);

Parameters	Type	Description
hFile	Input	Handle specifying an open file stream

no return value.

srFileGetErrorMessage

srFileGetErrorMessage() gets the last error message for the remote file, if any.

srDWORD srFileGetErrorMessage(srDWORD dwError, 
                              srCHAR * szBuff, 
                              srDWORD dwSize);

Parameters	Type	Description
dwError	Input	Error code
szBuff	Output	Pointer to a character buffer to populate with the error message.
dwSize	Input	Size in bytes of the buffer pointed to by szBuff.

Return Value	Description
srDWORD	0 on success, error code otherwise.

srFileGetTempName

srFileGetTempName() gets an unique name for a temporary file on the host.

srDWORD srFileGetTempName(srCHAR * szHostPath, 
                          srDWORD dwSize);

Parameters	Type	Description
szHostPath	Output	Pointer to a character buffer to populate with the file path name.
dwSize	Input	Size in bytes of the buffer pointed to by szHostPath.

Return Value	Description
srDWORD	0 on success, error code otherwise.

srFileRemove

srFileRemove() removes a file on the host.

srDWORD srFileRemove(const srCHAR * szHostPath);

Parameters	Type	Description
szHostPath	Input	Full path to the remote file (located on the host computer).

Return Value	Description
srDWORD	0 on success, error code otherwise.

srFileRename

srFileRename() moves/renames a file on the host.

srDWORD srFileRename(const srCHAR * szHostPathOld, 
                     const srCHAR * szHostPathNew);

Parameters	Type	Description
szHostPathOld	Input	Full path to the old remote file (located on the host computer).
szHostPathNew	Input	Full path to the new remote file (located on the host computer).

Return Value	Description
srDWORD	0 on success, error code otherwise.