Difference between revisions of "File Transfer Services"

From STRIDE Wiki
Jump to: navigation, search
 
(28 intermediate revisions by 4 users not shown)
Line 1: Line 1:
−
== Introduction ==
+
__NOTOC__
 +
Stride 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 | 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 ==
+
'''Example'''
  
−
== Reference ==
+
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.
  
−
=== srFileOpen ===
+
<source lang="c">
 +
srCHAR file[] = "/path/to/host/file";
 +
srBYTE readBuffer[1024] = {0};
 +
srFileHandle_t handle = 0;
 +
srDWORD result = 0;
 +
srDWORD totalBytesRead = 0;
  
−
srFileOpen() opens a file on the host computer.
+
/* 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, sizeof(readBuffer), &actualBytesRead)))
 +
    goto QUIT;
 +
 +
  if (actualBytesRead > 0)
 +
  {
 +
    totalBytesRead += actualBytesRead;
 +
    /* TODO - do something with the contents of the readBuffer */
 +
  }
 +
  else
 +
    break;
 +
}
 +
 +
srNOTE_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);
 +
  srNOTE_ERROR(errorBuffer);
 +
}
 +
 
 +
if (handle !=0)
 +
  srFileClose(handle);
 +
</source>
 +
 +
 +
== srFileOpen ==
 +
 +
srFileOpen() opens a file on the host computer.
 
<source lang="c">
 
<source lang="c">
−
srDWORD srTestPointExpect(const srCHAR * szHostPath,  
+
srDWORD srFileOpen(const srCHAR   * szHostPath,  
−
                          const srCHAR * szMode,
+
                  const srCHAR   * szMode,
−
                          srFileHandle_t * phFile);
+
                  srFileHandle_t * phFile);
 
</source>
 
</source>
  
Line 22: Line 69:
 
| szHostPath
 
| szHostPath
 
| Input
 
| Input
−
| Full path to the remote file (located on the host computer)
+
| Full path to the remote file (located on the host computer) <ref name="env">A full path to the remote file (located on the host computer) could reference host environment variables (e.g. ''$VAR/path/file'') using syntax of your choice - %VAR%, $VAR, $(VAR), or ${VAR}</ref>
 
|-
 
|-
 
| szMode
 
| szMode
 
| Input
 
| Input
 
| Mode string for opening the file - can be one of the following:
 
| Mode string for opening the file - can be one of the following:
−
* r
+
* <b>r</b> - open for reading
−
* w
+
* <b>w</b> - open for writing (creates file if it doesn't exist). Deletes content and overwrites the file.
−
* a
+
* <b>a</b> - open for appending (creates file if it doesn't exist)
 
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.
 
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.
 
|-
 
|-
Line 46: Line 93:
  
  
−
=== srFileClose ===
+
== srFileClose ==
  
 
srFileClose () closes a remote file associated with the specified handle.
 
srFileClose () closes a remote file associated with the specified handle.
Line 73: Line 120:
  
  
−
=== srFileSeek===
+
== srFileSeek ==
  
 
srFileSeek() seeks to the specified position within an open remote file stream by moving ''lOffset'' bytes relative to a position specified by ''eOrigin''.
 
srFileSeek() seeks to the specified position within an open remote file stream by moving ''lOffset'' bytes relative to a position specified by ''eOrigin''.
Line 113: Line 160:
  
  
−
=== srFileTell===
+
== srFileTell ==
  
 
srFileTell() returns the current position of <i>hFile</i> relative to the beginning of the file.
 
srFileTell() returns the current position of <i>hFile</i> relative to the beginning of the file.
Line 145: Line 192:
  
  
 +
== 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.
 +
 +
<source lang="c">
 +
srDWORD srFileRead(srFileHandle_t hFile,
 +
                  void * pvData,
 +
                  srDWORD dwBytesToRead,
 +
                  srDWORD * pdwBytesRead);
 +
</source>
 +
 +
{| border="1" cellspacing="0" cellpadding="10" style="align:left;" 
 +
| '''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.
 +
|}
 +
<br>
 +
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
 +
| '''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.
 +
 +
<source lang="c">
 +
srDWORD srFileWrite(srFileHandle_t hFile,
 +
                    const void * pvData,
 +
                    srDWORD dwBytesToWrite,
 +
                    srDWORD * pdwBytesWritten);
 +
</source>
 +
 +
{| border="1" cellspacing="0" cellpadding="10" style="align:left;" 
 +
| '''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.
 +
|}
 +
<br>
 +
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
 +
| '''Return Value'''
 +
| ''' Description'''
 +
|-
 +
| srDWORD
 +
| 0 on success, error code otherwise.
 +
|}
 +
 +
 +
== srFileGets ==
 +
 +
srFileGets () gets a string from an open remote file stream and stores the data in the memory pointed to by ''szBuff''. Reads characters from the current stream position to and including the first newline character, to the end of the stream, or until the number of characters read is equal to ''dwSize – 1'', whichever comes first.
 +
 +
<source lang="c">
 +
srDWORD srFileGets(srFileHandle_t hFile,
 +
                  srCHAR * szBuff,
 +
                  srDWORD dwSize);
 +
</source>
 +
 +
{| border="1" cellspacing="0" cellpadding="10" style="align:left;" 
 +
| '''Parameters'''
 +
| '''Type'''
 +
| '''Description'''
 +
|-
 +
| hFile
 +
| Input
 +
| Handle specifying an open file stream
 +
|-
 +
| szBuff
 +
| Output
 +
| Pointer to a block of memory with a maximum size of ''dwSize'' chars
 +
|-
 +
| dwSize
 +
| Input
 +
| Size in chars of the buffer pointed to by ''szBuff''
 +
|}
 +
<br>
 +
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
 +
| '''Return Value'''
 +
| ''' Description'''
 +
|-
 +
| srDWORD
 +
| 0 on success, error code otherwise.
 +
|}
 +
 +
 +
== srFilePuts ==
 +
 +
srFilePuts() puts a null-terminated string specified in ''szBuff'' to an open remote file stream. The current position of the stream is advanced by the number of bytes written.
 +
 +
<source lang="c">
 +
srDWORD srFilePuts(srFileHandle_t hFile,
 +
                  const srCHAR * szBuff);
 +
</source>
 +
 +
{| border="1" cellspacing="0" cellpadding="10" style="align:left;" 
 +
| '''Parameters'''
 +
| '''Type'''
 +
| '''Description'''
 +
|-
 +
| hFile
 +
| Input
 +
| Handle specifying an open file stream
 +
|-
 +
| szBuff
 +
| Output
 +
| Pointer to a null-terminated string
 +
|}
 +
<br>
 +
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
 +
| '''Return Value'''
 +
| ''' Description'''
 +
|-
 +
| srDWORD
 +
| 0 on success, error code otherwise.
 +
|}
 +
 +
 +
== srFileEOF ==
 +
 +
srFileEOF() checks whether the remote file's end of file flag is set.
 +
 +
<source lang="c">
 +
srBOOL srFileEOF(srFileHandle_t hFile);
 +
</source>
 +
 +
{| border="1" cellspacing="0" cellpadding="10" style="align:left;" 
 +
| '''Parameters'''
 +
| '''Type'''
 +
| '''Description'''
 +
|-
 +
| hFile 
 +
| Input
 +
| Handle specifying an open file stream
 +
|}
 +
<br>
 +
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
 +
| '''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.
 +
 +
<source lang="c">
 +
srBOOL srFileError(srFileHandle_t hFile);
 +
</source>
 +
 +
{| border="1" cellspacing="0" cellpadding="10" style="align:left;" 
 +
| '''Parameters'''
 +
| '''Type'''
 +
| '''Description'''
 +
|-
 +
| hFile 
 +
| Input
 +
| Handle specifying an open file stream
 +
|}
 +
<br>
 +
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
 +
| '''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
 +
 +
<source lang="c">
 +
void srFileClearErr(srFileHandle_t hFile);
 +
</source>
 +
 +
{| border="1" cellspacing="0" cellpadding="10" style="align:left;" 
 +
| '''Parameters'''
 +
| '''Type'''
 +
| '''Description'''
 +
|-
 +
| hFile 
 +
| Input
 +
| Handle specifying an open file stream
 +
|}
 +
 +
no return value.
  
  
−
=== TBD ===
+
== srFileGetErrorMessage ==
  
 +
srFileGetErrorMessage() gets the last error message for the remote file, if any.
  
 
<source lang="c">
 
<source lang="c">
 +
srDWORD srFileGetErrorMessage(srDWORD dwError,
 +
                              srCHAR * szBuff,
 +
                              srDWORD dwSize);
 +
</source>
  
 +
{| border="1" cellspacing="0" cellpadding="10" style="align:left;" 
 +
| '''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.
 +
|}
 +
<br>
 +
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
 +
| '''Return Value'''
 +
| ''' Description'''
 +
|-
 +
| srDWORD
 +
| 0 on success, error code otherwise.
 +
|}
  
−
/**
 
−
* Reads <i>uSize*uCount</i> bytes from an open remote file stream and stores the data in the memory pointed to by <i>pData</i>.
 
−
* The current position of the stream is advanced by the number of bytes read.
 
−
*
 
−
* @param hFile        Handle specifying an open file stream
 
−
* @param pvData        Pointer to a block of memory with a minimum size of <i>uSize</i> bytes
 
−
* @param dwBytesToRead Number of bytes to be read
 
−
* @param pdwBytesRead  Pointer to store the number of bytes successfully read.
 
−
*                  If this number differs from <i>uSize</i> either an error has occurred or the End Of File was reached.
 
−
*
 
−
* @return Zero on success, error code otherwise.
 
−
*/
 
−
srEXPORT srDWORD srFileRead(srFileHandle_t hFile, void * pvData, srDWORD dwBytesToRead, srDWORD * pdwBytesRead);
 
  
−
/**
+
== srFileGetTempName ==
−
* Writes <i>uSize*uCount</i> bytes from the memory location specified in <i>pBuffer</i> to an open remote file stream.
 
−
* The current position of the stream is advanced by the number of bytes written.
 
−
*
 
−
* @param hFile            Handle specifying an open file stream
 
−
* @param pvData            Pointer to a block of memory to read from - must contain <i>uSize</i> bytes of data.
 
−
* @param dwBytesToWrite    Number of bytes to be written
 
−
* @param pdwBytesWritten  Pointer to store the number of bytes successfully written.
 
−
*                  If this number differs from <i>uSize</i> an error has occurred.
 
−
*
 
−
* @return Zero on success, error code otherwise.
 
−
*/
 
−
srEXPORT srDWORD srFileWrite(srFileHandle_t hFile, const void * pvData, srDWORD dwBytesToWrite, srDWORD * pdwBytesWritten);
 
  
−
/**
+
srFileGetTempName() gets an unique name for a temporary file on the host.
−
* Flushes the content of the remote file.
 
−
*
 
−
* @param hFile  Handle specifying an open file stream
 
−
*
 
−
* @return Zero on success, error code otherwise.
 
−
*       
 
−
*/
 
−
srEXPORT srDWORD srFileFlush(srFileHandle_t hFile);
 
  
−
/**
+
<source lang="c">
−
* Checks whether the remote file's end of file flag is set.
+
srDWORD srFileGetTempName(srCHAR * szHostPath,  
−
*
+
                          srDWORD dwSize);
−
* @param hFile  Handle specifying an open file stream
+
</source>
−
*
 
−
* @return srTRUE if the EOF flag is set for the remote file, srFALSE otherwise.
 
−
*       
 
−
*/
 
−
srEXPORT srBOOL srFileEOF(srFileHandle_t hFile);
 
  
−
/**
+
{| border="1" cellspacing="0" cellpadding="10" style="align:left;" 
−
* Checks whether the remote file error flag has been set by a preceeding operation.
+
| '''Parameters'''
−
*
+
| '''Type'''
−
* @param hFile  Handle specifying an open file stream
+
| '''Description'''
−
*
+
|-
−
* @return srTRUE if the error flag is set for the remote file, srFALSE otherwise.
+
| szHostPath
−
*       
+
| Output
−
*/
+
| Pointer to a character buffer to populate with the file path name.).<ref name="env"/>
−
srEXPORT srBOOL srFileError(srFileHandle_t hFile);
+
|-
 +
| dwSize
 +
| Input
 +
| Size in bytes of the buffer pointed to by szHostPath.
 +
|}
 +
<br>
 +
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
 +
| '''Return Value'''
 +
| ''' Description'''
 +
|-
 +
| srDWORD
 +
| 0 on success, error code otherwise.
 +
|}
  
−
/**
 
−
* Clears the error flag for the remote file
 
−
*
 
−
* @param hFile  Handle specifying an open file stream
 
−
*       
 
−
*/
 
−
srEXPORT void srFileClearErr(srFileHandle_t hFile);
 
  
−
/**
+
== srFileRemove ==
−
* Gets the last error message for the remote file, if any.
 
−
*
 
−
* @param dwError Error code
 
−
* @param szBuff  Pointer to a character buffer to populate with the error message.
 
−
* @param dwSize  Size in bytes of the buffer pointed to by szBuff
 
−
*
 
−
* @return Zero on success, error code otherwise.
 
−
*       
 
−
*/
 
−
srEXPORT srDWORD srFileGetErrorMessage(srDWORD dwError, srCHAR * szBuff, srDWORD dwSize);
 
  
−
/**
+
srFileRemove() removes a file on the host.
−
* Gets an unique name for a temporary file.
+
 
−
*
+
<source lang="c">
−
  * @param szHostPath   Pointer to a character buffer to populate with the file path name.
+
srDWORD srFileRemove(const srCHAR * szHostPath);
−
* @param dwSize        Size in bytes of the buffer pointed to by szHostPath
+
</source>
−
*
+
 
−
* @return Zero on success, error code otherwise.
+
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"  
−
*       
+
| '''Parameters'''
−
*/
+
| '''Type'''
−
srEXPORT srDWORD srFileGetTempName(srCHAR * szHostPath, srDWORD dwSize);
+
| '''Description'''
 +
|-
 +
| szHostPath
 +
| Input
 +
| Full path to the remote file (located on the host computer).<ref name="env"/>
 +
|}
 +
<br>
 +
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
 +
| '''Return Value'''
 +
| ''' Description'''
 +
|-
 +
| srDWORD
 +
| 0 on success, error code otherwise.
 +
|}
  
−
/**
 
−
* Remove a file.
 
−
*
 
−
* @param szHostPath  Full path to the remote file (located on the host computer).
 
−
*
 
−
* @return Zero on success, error code otherwise.
 
−
*       
 
−
*/
 
−
srEXPORT srDWORD srFileRemove(const srCHAR * szHostPath);
 
  
 +
== srFileRename==
  
−
/**
+
srFileRename() moves/renames a file on the host.
−
* Rename/Move a file.
 
−
*
 
−
* @param szHostPathOld  Full path to the old remote file (located on the host computer).
 
−
* @param szHostPathNew  Full path to the new remote file (located on the host computer).
 
−
*
 
−
* @return Zero on success, error code otherwise.
 
−
*       
 
−
*/
 
−
srEXPORT srDWORD srFileRename(const srCHAR * szHostPathOld, const srCHAR * szHostPathNew);
 
  
 +
<source lang="c">
 +
srDWORD srFileRename(const srCHAR * szHostPathOld,
 +
                    const srCHAR * szHostPathNew);
 
</source>
 
</source>
 +
 +
{| border="1" cellspacing="0" cellpadding="10" style="align:left;" 
 +
| '''Parameters'''
 +
| '''Type'''
 +
| '''Description'''
 +
|-
 +
| szHostPathOld
 +
| Input
 +
| Full path to the old remote file (located on the host computer).<ref name="env"/>
 +
|-
 +
| szHostPathNew
 +
| Input
 +
| Full path to the new remote file (located on the host computer).<ref name="env"/>
 +
 +
|}
 +
<br>
 +
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
 +
| '''Return Value'''
 +
| ''' Description'''
 +
|-
 +
| srDWORD
 +
| 0 on success, error code otherwise.
 +
|}
 +
 +
 +
== srPrompt==
 +
 +
srPrompt() provides interactive console prompt on the host.
 +
 +
<source lang="c">
 +
srDWORD srPrompt(const srCHAR * szQuestion,
 +
                srCHAR * szAnswer,
 +
                srDWORD dwSize,
 +
                srWORD wTimeout);
 +
</source>
 +
 +
{| border="1" cellspacing="0" cellpadding="10" style="align:left;" 
 +
| '''Parameters'''
 +
| '''Type'''
 +
| '''Description'''
 +
|-
 +
| szQuestion
 +
| Input
 +
| Question to the user.
 +
|-
 +
| szAnswer
 +
| Input/Output
 +
| Default answer as input and actual answer as output
 +
|-
 +
| dwSize
 +
| Input
 +
|  Size in chars of the buffer pointed to by szAnswer
 +
|-
 +
| wTimeout
 +
| Input
 +
|  Timeout in seconds, where 0 means no timeout. In case of timeout the default answer will be used.
 +
|}
 +
<br>
 +
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
 +
| '''Return Value'''
 +
| ''' Description'''
 +
|-
 +
| srDWORD
 +
| 0 on success, error code otherwise.
 +
|}
 +
 +
 +
== Notes ==
 +
<references/>

Latest revision as of 09:41, 6 July 2015

Stride 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

Example

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[1024] = {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, sizeof(readBuffer), &actualBytesRead)))
    goto QUIT;

  if (actualBytesRead > 0)
  {
    totalBytesRead += actualBytesRead;
    /* TODO - do something with the contents of the readBuffer */
  }
  else 
    break;
}

srNOTE_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);
  srNOTE_ERROR(errorBuffer);
}
  
if (handle !=0)
  srFileClose(handle);


srFileOpen

srFileOpen() opens a file on the host computer. 

srDWORD srFileOpen(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) [1]
szMode Input Mode string for opening the file - can be one of the following:
  • r - open for reading
  • w - open for writing (creates file if it doesn't exist). Deletes content and overwrites the file.
  • a - open for appending (creates file if it doesn't exist)

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.


srFileGets

srFileGets () gets a string from an open remote file stream and stores the data in the memory pointed to by szBuff. Reads characters from the current stream position to and including the first newline character, to the end of the stream, or until the number of characters read is equal to dwSize – 1, whichever comes first. 

srDWORD srFileGets(srFileHandle_t hFile, 
                   srCHAR * szBuff, 
                   srDWORD dwSize);
Parameters Type Description
hFile Input Handle specifying an open file stream
szBuff Output Pointer to a block of memory with a maximum size of dwSize chars
dwSize Input Size in chars of the buffer pointed to by szBuff


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


srFilePuts

srFilePuts() puts a null-terminated string specified in szBuff to an open remote file stream. The current position of the stream is advanced by the number of bytes written. 

srDWORD srFilePuts(srFileHandle_t hFile, 
                   const srCHAR * szBuff);
Parameters Type Description
hFile Input Handle specifying an open file stream
szBuff Output Pointer to a null-terminated string


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.).[1]
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).[1]


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).[1]
szHostPathNew Input Full path to the new remote file (located on the host computer).[1]


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


srPrompt

srPrompt() provides interactive console prompt on the host. 

srDWORD srPrompt(const srCHAR * szQuestion, 
                 srCHAR * szAnswer, 
                 srDWORD dwSize, 
                 srWORD wTimeout);
Parameters Type Description
szQuestion Input Question to the user.
szAnswer Input/Output Default answer as input and actual answer as output
dwSize Input Size in chars of the buffer pointed to by szAnswer
wTimeout Input Timeout in seconds, where 0 means no timeout. In case of timeout the default answer will be used.


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


Notes

  1. ↑ 1.0 1.1 1.2 1.3 1.4 A full path to the remote file (located on the host computer) could reference host environment variables (e.g. $VAR/path/file) using syntax of your choice - %VAR%, $VAR, $(VAR), or ${VAR}
Retrieved from "https://www.stridewiki.com/index.php?title=File_Transfer_Services&oldid=14375"