|
|
|
|
30
File StreamingFileStream.h declares the API that this chapter describes. For more information on file streaming, see the chapter "Files and Databases" in the Palm OS Programmer's Companion.
openMode parameter to the
| operator (bitwise inclusive OR) to append to a primary mode selector one or more of the secondary mode selectors listed below.
fileModeDontOverwrite
|
Prevents fileModeReadWrite from discarding an existing stream having the same name; may only be specified together with fileModeReadWrite
|
fileModeLeaveOpen
| Leave stream open when application quits. Most applications should not use this option. |
fileModeExclusive
| No other application can open the stream until the application that opened it in this mode closes it. |
fileModeAnyTypeCreator
|
Accept any type/creator when opening or replacing an existing stream. Normally, the FileOpen function to open streams having a type or creator other than those specified.
|
fileModeTemporary
|
Delete the stream automatically when it is closed. For more information, see Comment section of |
Err FileClearerr (FileHand stream)
fileErr code if an error occurs. See the section "File Streaming Error Codes" for more information.
fileModeTemporary, it is deleted upon closing.
Err FileClose (FileHand stream)
fileErr code if an error occurs. See the section "File Streaming Error Codes" for more information.
op parameter on the stream file stream.
Err FileControl (FileOpEnum op, FileHand stream, void* valueP, Int32* valueLenP)
|
The operation to perform, and its associated formal parameters. See the Comments section for a list of possible values. |
--> |
Open stream handle if required for file stream operation. |
<--> |
Pointer to value or buffer, as required. This parameter is defined by the selector passed as the value of the op parameter. For details, see the Comments section. |
<--> |
Pointer to value or buffer, as required. This parameter is defined by the selector passed as the value of the op parameter. For details, see the Comments section. |
op parameter, or an error code resulting from the requested operation. For details, see the Comments section.
fileOpNone
| No-op. |
fileOpDestructiveReadMode
| Enter destructive read mode, and rewind stream to its beginning. Once in this mode, there is no turning back: stream's contents after closing (or crash) are undefined. |
| Destructive read mode deletes blocks as data are read, thus freeing storage automatically. Once in destructive read mode, you cannot re-use the file stream--the contents of the stream are undefined after it is closed or after a crash. | |
Writing to files opened without write access or those that are in destructive read state is not allowed; thus, you cannot call the | |
ARGUMENTS:
stream = open stream handle
valueP = NULL
valueLenP = NULL
| |
RETURNS:
zero on success;
fileErr... on error
| |
fileOpGetEOFStatus
|
Get end-of-file status (like C runtime's feof) (err = fileErrEOF). Indicates end of file condition. Use |
ARGUMENTS:
stream = open stream handle
valueP = NULL
valueLenP = NULL
| |
| RETURNS: zero if not end of file; non-zero if end of file | |
fileOpGetLastError
|
Get error code from last operation on stream, and clear the last error code value. Doesn't change status of EOF or I/O errors --use |
ARGUMENTS:
stream = open stream handle
valueP = NULL
valueLenP = NULL
| |
| RETURNS: Error code from last file stream operation | |
fileOpClearError
| Clear I/O and EOF error status and last error. |
ARGUMENTS:
stream = open stream handle
valueP = NULL
valueLenP = NULL
| |
RETURNS:
zero on success; fileErr... on error
| |
fileOpGetIOErrorStatus
|
Get I/O error status (like C runtime's ferror). Use |
ARGUMENTS:
stream = open stream handle
valueP = NULL
valueLenP = NULL
| |
| RETURNS: zero if not I/O error; non-zero if I/O error is pending. | |
fileOpGetCreatedStatus
|
Find out whether file was created by |
ARGUMENTS:
stream = open stream handle
valueP = Pointer to Boolean
valueLenP = Pointer to Int32 variable set to sizeof(Boolean)
| |
RETURNS:
zero on success; fileErr... on error. The Boolean variable will be set to non-zero if the file was created.
| |
fileOpGetOpenDbRef
|
Get the open database reference (handle) of the underlying database that implements the stream (NULL if none); this is needed for performing Palm OS-specific operations on the underlying database, such as changing or getting creator and type, version, backup/reset bits, and so on.
|
ARGUMENTS:
stream = open stream handle
valueP = Pointer to DmOpenRef variable
valueLenP = Pointer to Int32 variable set to sizeof(DmOpenRef)
| |
RETURNS:
zero on success; fileErr... on error. The DmOpenRef variable will be set to the file's open db reference that may be passed to Data Manager calls;
| |
| WARNING: Do not make any changes to the data of the underlying database -- doing so will corrupt the file stream. | |
fileOpFlush
| Flush any cached data to storage. |
ARGUMENTS:
stream = open stream handle
valueP = NULL
valueLenP = NULL
| |
RETURNS:
zero on success; fileErr... on error;
|
Err FileDelete (UInt16 cardNo, Char* nameP)
|
Card on which the file stream to delete resides. Currently, no Palm OS® devices support multiple cards, so this value must be 0. |
|
String that is the name of the stream to delete. |
fileErr code if an error occurs. See the section "File Streaming Error Codes" for more information.
Int32 FileDmRead (FileHand stream, void* startOfDmChunkP, Int32 destOffset, Int32 objSize, Int32 numObj, Err* errP)
--> |
Handle to open stream. |
--> |
Pointer to beginning of chunk, record or resource residing in a database. |
|
Offset from startOfDmChunkP (base pointer) to the destination area (must be >= 0). |
|
Size of each stream object to read. |
|
Number of stream objects to read. |
<--> |
Pointer to variable that is to hold the error code returned by this function. Pass NULL to ignore. See the section "File Streaming Error Codes" for more information. |
errP parameter or by calling the NULL pointer was passed as the value of the errP parameter when the FileDmRead function was called and an error was encountered, *errP holds a non-zero error code when the function returns. In addition, the fileErrEOF indicates end of file condition).
Err FileEOF (FileHand stream)
feof function provided by the C programming language runtime library.
Err FileError (FileHand stream)
ferror runtime function.
Err FileFlush (FileHand stream)
fileErr code if an error occurs. See the section "File Streaming Error Codes" for more information.
fflush function provided by the C programming language runtime library, you only need to call it explicitly under circumstances similar to those in which you would call fflush explicitly.
Err FileGetLastError (FileHand stream)
openMode parameter.
FileHand FileOpen (UInt16 cardNo, Char* nameP, UInt32 type, UInt32 creator, UInt32 openMode, Err* errP)
|
Card on which the file stream to open resides. Currently, no Palm OS devices support multiple cards, so this value must be 0. |
--> |
Pointer to text string that is the name of the file stream to open or create. This value must be a valid name--no wildcards allowed, must not be NULL. |
|
Creator of stream to open or create. Pass 0 for wildcard, in which case the current application's creator ID is used for the creator of the stream this function creates. |
|
Mode in which to open the file stream. You must specify only one primary mode selector. Additionally, you can use the | operator (bitwise inclusive OR) to append one or more secondary mode selectors to the primary mode selector. See "Primary Open Mode Constants" and "Secondary Open Mode Constants" for the list of possible values. |
|
|
<--> |
Pointer to variable that is to hold the error code returned by this function. Pass NULL to ignore. See the section "File Streaming Error Codes" for a list of error codes. |
0.
fileModeReadOnly, fileModeReadWrite, fileModeUpdate, and fileModeAppend modes are mutually exclusive--pass only one of them to the FileOpen function!
fileModeTemporary open mode is used and the file type passed to FileOpen is 0, the FileOpen function uses sysFileTTemp (defined in SystemMgr.rh) for the file type, as recommended. In future versions of Palm OS, this configuration will enable the automatic cleanup of undeleted temporary files after a system crash. Automatic post-crash cleanup is not implemented in current versions of Palm OS.
fileModeAnyTypeCreator selector as a flag in the openMode parameter to the fileModeLeaveOpen mode is an esoteric option that most applications should not use. It may be useful for a library that needs to open a stream from the current application's context and keep it open even after the current application quits. By default, Palm OS automatically closes all databases that were opened in a particular application's context when that application quits. The fileModeLeaveOpen option overrides this default behavior.
Int32 FileRead (FileHand stream, void* bufP, Int32 objSize, Int32 numObj, Err* errP)
--> |
Handle to open stream. |
--> |
Pointer to beginning of buffer into which data is read |
|
Size of each stream object to read. |
|
Number of stream objects to read. |
<--> |
Pointer to variable that is to hold the error code returned by this function. Pass NULL to ignore. See the section "File Streaming Error Codes" for a list of error codes. |
errP parameter or by calling the NULL pointer was passed as the value of the errP parameter when the FileRead function was called and an error was encountered, *errP holds a non-zero error code when the function returns. In addition, the Err FileRewind (FileHand stream)
fileErr code if an error occurs. See the section "File Streaming Error Codes" for more information.
Err FileSeek (FileHand stream, Int32 offset, FileOriginEnum origin)
--> |
Handle to open stream. |
|
Position to set, expressed as the number of bytes from origin. This value may be positive, negative, or 0. |
|
Describes the origin of the position change. Possible values are: |
|
From the beginning (first data byte of file). |
|
From the current position. |
|
From the end of file (one position beyond last data byte). |
fileErr code if an error occurs. See the section "File Streaming Error Codes" for more information.
fseek function provided by the C programming language runtime library.
Int32 FileTell (FileHand stream, Int32* fileSizeP, Err* errP)
--> |
Handle to open stream. |
<-> |
Pointer to variable that holds value describing size of stream in bytes when this function returns. Pass NULL to ignore. |
<--> |
Pointer to variable that is to hold the error code returned by this function. Pass NULL to ignore. See the section "File Streaming Error Codes" for a list of possible error codes. |
-1 as a signed long integer.
Err FileTruncate (FileHand stream, Int32 newSize)
fileErr code if an error occurs. See the section "File Streaming Error Codes" for a list of possible error codes.
Int32 FileWrite (FileHand stream, void* dataP, Int32 objSize, Int32 numObj, Err* errP)
--> |
Handle to open stream. |
--> |
Pointer to buffer holding data to write. |
|
Size of each stream object to write; must be >= 0. |
|
Number of stream objects to write. |
<--> |
Optional pointer to variable that holds the error code returned by this function. Pass NULL to ignore. See the section "File Streaming Error Codes" for a list of possible error codes. |
FileWrite function can append data to the stream, but it also preserves the current stream position so that subsequent reads pick up where they left off (you can think of this as a pseudo-pipe).
|
|
|
|