File Transfer Services

Reference

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.

TBD

/**
 * 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);

/**
 * 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);

/**
 * 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);

/**
 * Checks whether the remote file's end of file flag is set.
 * 
 * @param hFile  Handle specifying an open file stream
 * 
 * @return srTRUE if the EOF flag is set for the remote file, srFALSE otherwise.
 *         
 */
srEXPORT srBOOL srFileEOF(srFileHandle_t hFile);

/**
 * Checks whether the remote file error flag has been set by a preceeding operation.
 * 
 * @param hFile  Handle specifying an open file stream
 * 
 * @return srTRUE if the error flag is set for the remote file, srFALSE otherwise.
 *         
 */
srEXPORT srBOOL srFileError(srFileHandle_t hFile);

/**
 * Clears the error flag for the remote file
 * 
 * @param hFile  Handle specifying an open file stream
 *         
 */
srEXPORT void srFileClearErr(srFileHandle_t hFile);

/**
 * 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);

/**
 * Gets an unique name for a temporary file.
 *
 * @param szHostPath    Pointer to a character buffer to populate with the file path name.
 * @param dwSize        Size in bytes of the buffer pointed to by szHostPath
 * 
 * @return Zero on success, error code otherwise.
 *         
 */
srEXPORT srDWORD srFileGetTempName(srCHAR * szHostPath, srDWORD dwSize);

/**
 * 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);


/**
 * 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);