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.

TBD

/**
 * Closes the remote file associated with <i>hFile</i>
 * 
 * @param hFile  Handle specifying an open file stream
 * 
 * @return Zero on success, error code otherwise.
 */
srEXPORT srDWORD srFileClose(srFileHandle_t hFile);

/**
 * Seeks to the specified position within an open remote file stream by adding <i>lOffset</i> to a reference position
 * specisfied by <i>eOrigin</i>
 * 
 * @param hFile     Handle specifying an open file stream
 * @param lOffset   Number of bytes to offset from <i>eOrigin</i>
 * @param eOrigin   Position to which <i>lOffset</i> is added. It is specified by one of the following enumerations:
 *                  <ul>
 *                  <li>srSEEK_BEGIN</li>
 *                  <li>srSEEK_CUR</li>
 *                  <li>srSEEL_END</li>
 *                  </ul>
 * 
 * @return Zero on success, error code otherwise.
 */
srEXPORT srDWORD srFileSeek(srFileHandle_t hFile, srLONG lOffset, srFileSeekOrigin_e eOrigin);

/**
 * Returns the current position of <i>hFile</i>
 * 
 * @param hFile     Handle specifying an open file stream
 * @param plOffset  Pointer to store the current position in the file
 * 
 * @return Zero on success, error code otherwise.
 */
srEXPORT srDWORD srFileTell(srFileHandle_t hFile, srLONG* plOffset);

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