File Streaming
 

 < Home   < Developers   < Development Support   < Documentation

32 File Streaming


 Table of Contents  |  < Previous  |  Next >  |  Index
   
   

Title -
Palm OS® Programmer's API Reference

Part II: System Management

32 File Streaming

File Streaming Constants

Primary Open Mode Constants

Secondary Open Mode Constants

File Streaming Functions

FileClearerr

FileClose

FileControl

FileDelete

FileDmRead

FileEOF

FileError

FileFlush

FileGetLastError

FileOpen

FileRead

FileRewind

FileSeek

FileTell

FileTruncate

FileWrite

File Streaming Error Codes

       

This chapter provides reference material for the file streaming API.

File Streaming Constants

File Streaming Functions

File Streaming Error Codes

The header file FileStream.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, vol. I.

File Streaming Constants

Primary Open Mode Constants

This section lists constants passed in the openMode parameter to the FileOpen function. These constants specify the mode in which a file stream is opened.

For each file stream, you must pass to the FileOpen function only one of the primary mode selectors listed.

Constant Values

fileModeReadOnly
Open for read-only access
fileModeReadWrite
Open/create for read/write access, discarding any previous version of stream
fileModeUpdate
Open/create for read/write, preserving previous version of stream if it exists
fileModeAppend
Open/create for read/write, always writing to the end of the stream

Secondary Open Mode Constants

You can use 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 opens only streams having the specified creator and type. Setting this option enables 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 FileOpen function description.

File Streaming Functions

FileClearerr

Purpose

Clear I/O error status, end of file error status, and last error.

Prototype

Err FileClearerr (FileHand stream)

Parameters

--> stream Handle to open stream.

Result

0 if no error, or a fileErr code if an error occurs. See the section "File Streaming Error Codes" for more information.

Compatibility

Implemented only if 3.0 New Feature Set is present.

See Also

FileGetLastError, FileRewind

FileClose

Purpose

Close the file stream and destroy its handle. If the stream was opened with fileModeTemporary, it is deleted upon closing.

Prototype

Err FileClose (FileHand stream)

Parameters

--> stream Handle to open stream.

Result

0 if no error, or a fileErr code if an error occurs. See the section "File Streaming Error Codes" for more information.

Compatibility

Implemented only if 3.0 New Feature Set is present.

FileControl

Purpose

Perform the operation specified by the op parameter on the stream file stream.

Prototype

Err FileControl (FileOpEnum op, FileHand stream, void *valueP, Int32 *valueLenP)

Parameters

opThe operation to perform, and its associated formal parameters. See the Comments section for a list of possible values.
--> stream Open stream handle if required for file stream operation.
<--> valueP 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.
<--> valueLenP 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.

Result

Returns either a value defined by the selector passed as the argument to the op parameter, or an error code resulting from the requested operation. For details, see the Comments section.

Comments

Normally, you do not call the FileControl function yourself; it is called for you by most of the other file streaming functions and macros to perform common file streaming operations. You can call FileControl yourself to enable specialized read modes.

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 FileWrite, FileSeek, or FileTruncate functions on a stream that is in destructive read mode. One exception to this rule applies to streams that were opened in "write + append" mode and then switched into destructive read state. In this case, the 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).

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 FileClearerr to clear this error status.

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 FileClearerr to reset all error codes.

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 FileClearerr to clear this error status.

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 FileOpen function

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;

Compatibility

Implemented only if 3.0 New Feature Set is present.

See Also

FileClearerr, FileEOF, FileError, FileFlush, FileGetLastError, FileRewind

FileDelete

Purpose

Deletes the specified file stream from the specified card. Only a closed stream may be passed to this function.

Prototype

Err FileDelete (UInt16 cardNo, const Char *nameP)

Parameters

cardNoCard on which the file stream to delete resides. Currently, no Palm OS® devices support multiple cards, so this value must be 0.
namePString that is the name of the stream to delete.

Result

0 if no error, or a fileErr code if an error occurs. See the section "File Streaming Error Codes" for more information.

Compatibility

Implemented only if 3.0 New Feature Set is present.

See Also

FileOpen

FileDmRead

Purpose

A macro that reads data from a file stream into a chunk, record, or resource residing in a database.

Prototype

Int32 FileDmRead (FileHand stream, void *startOfDmChunkP, Int32 destOffset, Int32 objSize, Int32 numObj, Err *errP)

Parameters

--> stream Handle to open stream.
--> startOfDmChunkPPointer to beginning of chunk, record or resource residing in a database.
destOffsetOffset from startOfDmChunkP (base pointer) to the destination area (must be >= 0).
objSizeSize of each stream object to read.
numObjNumber of stream objects to read.
<--> errPPointer 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.

Result

The number of whole objects that were read-note that the number of objects actually read may be less than the number requested.

Comments

When the number of objects actually read is less than the number requested, you may be able to determine the cause of this result by examining the return value of the errP parameter or by calling the FileGetLastError function. If the cause is insufficient data in the stream to satisfy the full request, the current stream position is at end-of-file and the "end of file" indicator is set. If a non-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 FileError and FileEOF functions may be used to check for I/O errors.

Compatibility

Implemented only if 3.0 New Feature Set is present.

See Also

FileRead, FileError, FileEOF

FileEOF

Purpose

Get end-of-file status (err = fileErrEOF indicates end of file condition).

Prototype

Err FileEOF (FileHand stream)

Parameters

--> stream Handle to open stream.

Result

0 if not end of file; non-zero if end of file. See the section "File Streaming Error Codes" for more information.

Comments

This function's behavior is similar to that of the feof function provided by the C programming language runtime library.

Use FileClearerr to clear the I/O error status.

Compatibility

Implemented only if 3.0 New Feature Set is present.

See Also

FileClearerr, FileGetLastError, FileRewind

FileError

Purpose

Get I/O error status.

Prototype

Err FileError (FileHand stream)

Parameters

--> stream Handle to open stream.

Result

0 if no error, and non-zero if an I/O error indicator has been set for this stream. See the section "File Streaming Error Codes" for more information.

Comments

This function's behavior is similar to that of the C programming language's ferror runtime function.

Use FileClearerr to clear the I/O error status.

Compatibility

Implemented only if 3.0 New Feature Set is present.

See Also

FileClearerr, FileGetLastError, FileRewind

FileFlush

Purpose

Flush cached data to storage.

Prototype

Err FileFlush (FileHand stream)

Parameters

--> stream Handle to open stream.

Result

0 if no error, or a fileErr code if an error occurs. See the section "File Streaming Error Codes" for more information.

Comments

It is not always necessary to call this function explicitly-certain operations flush the contents of a stream automatically; for example, streams are flushed when they are closed. Because this function's behavior is similar to that of the 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.

Compatibility

Implemented only if 3.0 New Feature Set is present.

FileGetLastError

Purpose

Get error code from last operation on file stream, and clear the last error code value (will not change end of file or I/O error status -- use FileClearerr to reset all error codes)

Prototype

Err FileGetLastError (FileHand stream)

Parameters

--> stream Handle to open stream.

Result

Error code returned by the last file stream operation. See the section "File Streaming Error Codes" for more information.

Compatibility

Implemented only if 3.0 New Feature Set is present.

See Also

FileClearerr, FileEOF, FileError

FileOpen

Purpose

Open existing file stream or create an open file stream for I/O in the mode specified by the openMode parameter.

Prototype

FileHand FileOpen (UInt16 cardNo, const Char *nameP, UInt32 type, UInt32 creator, UInt32 openMode, Err *errP)

Parameters

cardNoCard on which the file stream to open resides. Currently, no Palm PoweredTM devices support multiple cards, so this value must be 0.
--> namePPointer 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.
typeFile type of stream to open or create. Pass 0 for wildcard, in which case sysFileTFileStream is used if the stream needs to be created and fileModeTemporary is not specified. If type is 0 and fileModeTemporary is specified, then sysFileTTemp is used for the file type of the stream this function creates.
creatorCreator 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.
openModeMode 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.
<--> errPPointer 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.

Result

If successful, returns a handle to an open file stream; otherwise, returns 0.

In some cases, on some platforms, FileOpen returns a non-zero value when it has failed to open a file; thus, it is always a good idea to check the errP parameter value to determine if an error has occurred.

Comments

The fileModeReadOnly, fileModeReadWrite, fileModeUpdate, and fileModeAppend modes are mutually exclusive-pass only one of them to the FileOpen function!

When the 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.

To open a file stream even if it has a different type and creator than specified, pass the fileModeAnyTypeCreator selector as a flag in the openMode parameter to the FileOpen function.

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.

Compatibility

Implemented only if 3.0 New Feature Set is present.

FileRead

Purpose

A macro that reads data from a stream into a buffer. Do not use this macro to read data into a chunk, record or resource residing in a database-you must use the FileDmRead macro for such operations.

Prototype

Int32 FileRead (FileHand stream, void *bufP, Int32 objSize, Int32 numObj, Err *errP)

Parameters

--> stream Handle to open stream.
--> bufPPointer to beginning of buffer into which data is read
objSizeSize of each stream object to read.
numObjNumber of stream objects to read.
<--> errPPointer 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.

Result

The number of whole objects that were read-note that the number of objects actually read may be less than the number requested.

Comments

Do not use this macro to read data into a chunk, record or resource residing in a database-you must use the FileDmRead macro for such operations.

When the number of objects actually read is fewer than the number requested, you may be able to determine the cause of this result by examining the return value of the errP parameter or by calling the FileGetLastError function. If the cause is insufficient data in the stream to satisfy the full request, the current stream position is at end-of-file and the "end of file" indicator is set. If a non-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 FileError and FileEOF functions may be used to check for I/O errors.

Compatibility

Implemented only if 3.0 New Feature Set is present.

See Also

FileDmRead

FileRewind

Purpose

Reset position marker to beginning of stream and clear all error codes.

Prototype

Err FileRewind (FileHand stream)

Parameters

--> stream Handle to open stream.

Result

0 if no error, or a fileErr code if an error occurs. See the section "File Streaming Error Codes" for more information.

Compatibility

Implemented only if 3.0 New Feature Set is present.

See Also

FileSeek, FileTell, FileClearerr, FileEOF, FileError, FileGetLastError

FileSeek

Purpose

Set current position within a file stream, extending the stream as necessary if it was opened with write access.

Prototype

Err FileSeek (FileHand stream, Int32 offset, FileOriginEnum origin)

Parameters

--> stream Handle to open stream.
offsetPosition to set, expressed as the number of bytes from origin. This value may be positive, negative, or 0.
originDescribes the origin of the position change. Possible values are:
fileOriginBeginning From the beginning (first data byte of file).
fileOriginCurrent From the current position.
fileOriginEnd From the end of file (one position beyond last data byte).

Result

0 if no error, or a fileErr code if an error occurs. See the section "File Streaming Error Codes" for more information.

Comments

Attempting to seek beyond end-of-file in a read-only stream results in an I/O error.

This function's behavior is similar to that of the fseek function provided by the C programming language runtime library.

Compatibility

Implemented only if 3.0 New Feature Set is present.

See Also

FileRewind, FileTell

FileTell

Purpose

Retrieves the current position and, optionally, file size, of a stream.

Prototype

Int32 FileTell (FileHand stream, Int32 *fileSizeP, Err *errP)

Parameters

--> stream Handle to open stream.
<-> fileSizePPointer to variable that holds value describing size of stream in bytes when this function returns. Pass NULL to ignore.
<--> errPPointer 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.

Result

If successful, returns current position, expressed as an offset in bytes from the beginning of the stream. If an error was encountered, returns -1 as a signed long integer.

Comments

The FileTell function can return the size of the input stream; as such, it provides some of the functionality of the standard C library stat function. Note, however, that unlike the stat function, FileTell requires that the file be open.

Compatibility

Implemented only if 3.0 New Feature Set is present.

See Also

FileRewind, FileSeek

FileTruncate

Purpose

Truncate the file stream to a specified size; not allowed on streams open in destructive read mode or read-only mode.

Prototype

Err FileTruncate (FileHand stream, Int32 newSize)

Parameters

--> stream Handle of open stream.
newSizeNew size; must not exceed current stream size.

Result

0 if no error, or a fileErr code if an error occurs. See the section "File Streaming Error Codes" for a list of possible error codes.

Compatibility

Implemented only if 3.0 New Feature Set is present.

See Also

FileTell

FileWrite

Purpose

Write data to a stream.

Prototype

Int32 FileWrite (FileHand stream, const void *dataP, Int32 objSize, Int32 numObj, Err *errP)

Parameters

--> stream Handle to open stream.
--> dataPPointer to buffer holding data to write.
objSizeSize of each stream object to write; must be 0.
numObjNumber of stream objects to write.
<--> errPOptional 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.

Result

The number of whole objects that were written-note that the number of objects actually written may be less than the number requested. Should available storage be insufficient to satisfy the entire request, as much of the requested data as possible is written to the stream, which may result in the last object in the stream being incomplete.

Comments

Writing to files opened without write access or those that are in destructive read state is not allowed; thus, you cannot call the FileWrite, FileSeek, or FileTruncate functions on a stream that is in destructive read mode. One exception to this rule applies to streams that were opened in "write + append" mode and then switched into destructive read state. In this case, the 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).

Compatibility

Implemented only if 3.0 New Feature Set is present.

File Streaming Error Codes

This section lists all error codes returned by the file streaming functions.

Error Code
Value
Meaning
fileErrMemErr
(fileErrorClass|1)
Out of memory error
fileErrInvalidParam
(fileErrorClass|2)
Invalid parameter value passed
fileErrCorruptFile
(fileErrorClass|3)
Alleged stream is corrupted, invalid, or not a stream
fileErrNotFound
(fileErrorClass|4)
Couldn't find the stream
fileErrTypeCreatorMismatch
(fileErrorClass|5)
Type and/or creator not what was specified
fileErrReplaceError
(fileErrorClass|6)
Couldn't replace existing stream
fileErrCreateError
(fileErrorClass|7)
Couldn't create new stream
fileErrOpenError
(fileErrorClass|8)
Generic open error
fileErrInUse
(fileErrorClass|9)
Stream couldn't be opened or deleted because it is in use
fileErrReadOnly
(fileErrorClass|10)
Couldn't open in write mode because existing stream is read-only
fileErrInvalidDescriptor
(fileErrorClass|11)
Invalid file descriptor (FileHandle)
fileErrCloseError
(fileErrorClass|12)
Error closing the stream
fileErrOutOfBounds
(fileErrorClass|13)
Attempted operation went out of bounds of the stream
fileErrPermissionDenied
(fileErrorClass|14)
Couldn't write to a stream open for read-only access
fileErrIOError
(fileErrorClass|15)
Generic I/O error
fileErrEOF
(fileErrorClass|16)
End-of-File error
fileErrNotStream
(fileErrorClass|17)
Attempted to open an entity that is not a stream