SFBFilePort

Wrapper Class for the IFilePort interface.

#include <SFBFilePort.h.hpp>

class SFBFilePort : public SFBPort;

SFMTYPEDEFWRAPPER(SFBFilePort)

Inheritance diagram

Version

BREW 2.0	BREW 2.1	BREW 3.1	BREW 4.0
X	X	X	O

Reference

BREW API IFilePort

Member

Public Functions
`SFCError`	Creat( `ACharConstPtr` path ) This function is the same as SFBFilePort::OpenEx() with nFlags equal to FS_O_WRONLY\|FS_O_CREAT\|FS_O_TRUNC.
`SFCError`	Creat( `SFXAnsiStringConstRef` path ) This function is the same as SFBFilePort::OpenEx() with nFlags equal to FS_O_WRONLY\|FS_O_CREAT\|FS_O_TRUNC.
`SFCError`	GetLastError( `Void` ) Returns the specific BREW-defined error code from the last SFBFilePort::Read(), SFBFilePort::Write(), or SFBFilePort::Seek() operation that returned IPORT_ERROR.
`SFCError`	Lock( `UInt32` lock ) Applies or removes a lock on the file opened with associated SFBFilePort instance.
static `SFBFilePortSmp`	NewInstance( `SFCErrorPtr` exception = null ) Create a new SFBFilePort instance.
static `SFBFilePortSmp`	NewInstance( `AEECLSID` id , `SFCErrorPtr` exception = null ) Create a new SFBFilePort instance.
`SFCError`	OpenEx( `ACharConstPtr` path , `SInt32` flags ) Opens an existing file, optionally after creating a new file.
`SFCError`	OpenEx( `SFXAnsiStringConstRef` path , `SInt32` flags ) Opens an existing file, optionally after creating a new file.
`SFCError`	Read( `VoidPtr` buffer , `SInt32` size ) Reads bytes from a file currently open for reading.
`SFCError`	Read( `SFXBufferPtr` buffer ) Reads bytes from a file currently open for reading.
`SFCError`	Rewind( `Void` ) This function is the same as SFBFilePort::Seek() with nOffset equal to zero and nWhence equal to FS_SEEK_SET.
`SFCError`	Seek( `SInt32` offset , `SInt32` whence ) Reposition the file point in an open file.
`SFCError`	Stat( `FSStat *` buffer , `SInt32` size ) Obtains information about an open file.
`SFCError`	StatVFS( `FSStatVFS *` buffer , `SInt32` size ) Obtains information about the virtual file system containing an open file.
`SFCError`	Truncate( `SInt32` length ) Truncate a file to the specified length.
`SFCError`	Close( `Void` ) (inherits from SFBPort) Close an opened port or stops a open in progress.
static `Bool`	Exhausted( `SInt32` code ) (inherits from SFBSource) Determine if a SFBSource, a SFBPeek, or a SFBGetLine is out of data.
`SFCError`	IOCtl( `SInt32` option , `UInt32` val ) (inherits from SFBPort) Allow some control over the behaviour of an SFBPort.
`SFCError`	Open( `ACharConstPtr` port ) (inherits from SFBPort) Open the specified prt.
`SFCError`	Open( `SFXAnsiStringConstRef` port ) (inherits from SFBPort) Open the specified prt.
`SFCError`	QueryInterface( `AEECLSID` clsid , `VoidHandle` handle ) (inherits from SFBQuery) Ask an object for another API contract from the object in question.
`SFCError`	QueryInterface( `AEECLSID` clsid , `SFBBaseSmpPtr` handle ) (inherits from SFBQuery) Ask an object for another API contract from the object in question.
`SFBBaseSmp`	QueryInterface( `AEECLSID` clsid ) (inherits from SFBQuery) Ask an object for another API contract from the object in question.
`Void`	Readable( `SFXCallbackPtr` callback ) (inherits from SFBSource) Schedule a callback to be called when SFBSource::Read() is able to return something other than ISOURCE_WAIT.
`Void`	Self( `AEECLSID` clsidReq , `SFBQuerySmpPtr` clone , `AEECLSID` clsidImp ) (inherits from SFBQuery) Helper macro for those implementing an object with a single interface.
`SFBQuerySmp`	Self( `AEECLSID` clsidReq , `AEECLSID` clsidImp ) (inherits from SFBQuery) Helper macro for those implementing an object with a single interface.
`SInt32`	Write( `ACharConstPtr` port , `SInt32` bufSize ) (inherits from SFBPort) Copy bytes from the specified buffer to the source stream.
`SInt32`	Write( `SFXAnsiStringConstRef` buf ) (inherits from SFBPort) Copy bytes from the specified buffer to the source stream.
`SInt32`	Write( `SFXBufferConstRef` buf ) (inherits from SFBPort) Copy bytes from the specified buffer to the source stream.
`Void`	Writeable( `SFXCallbackPtr` callback ) (inherits from SFBPort) Schedule a function to be called when SFBPort::Write() would return something other than AEEPORT_WAIT.

Protected Functions
static `SFBBaseSmp`	FactoryByCreate( `AEECLSID` id , `SFCErrorPtr` exception = null ) (inherits from SFBBase) Create the instance for the specified ClassID's interface.
static `SFBBaseSmp`	FactoryByQuery( `SFBQuerySmpConstRef` query , `AEECLSID` id , `SFCErrorPtr` exception = null ) (inherits from SFBBase) Create the instance for the specified ClassID's interface using the SFBQuery instance.

SFBFilePort::Creat

This function is the same as SFBFilePort::OpenEx() with nFlags equal to FS_O_WRONLY|FS_O_CREAT|FS_O_TRUNC.

[ public ]
SFCError Creat(
    ACharConstPtr path   // the path to the file of interest
);

[ public ]
SFCError Creat(
    SFXAnsiStringConstRef path   // the path to the file of interest
);

Reference

BREW API IFilePort_Creat | SFBFilePort::OpenEx

SFBFilePort::GetLastError

Returns the specific BREW-defined error code from the last SFBFilePort::Read(), SFBFilePort::Write(), or SFBFilePort::Seek() operation that returned IPORT_ERROR.

[ public ]
SFCError GetLastError(Void);

Return value

A specific BREW-defined error code.

Reference

BREW API IFilePort::GetLastError

SFBFilePort::Lock

Applies or removes a lock on the file opened with associated SFBFilePort instance.

[ public ]
SFCError Lock(
    UInt32 lock   // set to 1 (TRUE) to lock, 0 (FALSE) for unlock 
);

Return value

Returns AEE_SUCCESS if the lock/unlock operations is successful otherwise; a BREW-defined error code is returned.

Description

A file has to be opened by SFBFilePort before it can be locked/unlocked. By default all locks are advisory and exclusive.

Advisory lock implies that file system will not restrict any operation on a file which has been locked i.e a locked file can be accessed without using advisory locks. Advisory locks allow cooperating processes to perform consistent operations on files.

Exclusive lock implies that once a file has been locked, any request for locking the same file from any process will fail till the file has been unlocked again.

Reference

BREW API IFilePort_Lock | SFBFileSystem::Access

SFBFilePort::NewInstance

Create a new SFBFilePort instance.

[ public, static ]
SFBFilePortSmp NewInstance(
    SFCErrorPtr exception = null   // Error
);

[ public, static ]
SFBFilePortSmp NewInstance(
    AEECLSID id                    // Class ID
    SFCErrorPtr exception = null   // Error
);

SFBFilePort::OpenEx

Opens an existing file, optionally after creating a new file.

[ public ]
SFCError OpenEx(
    ACharConstPtr path   // the path to the file of interest 
    SInt32 flags         // bitwise or of one or more FS_O_* flags 
);

[ public ]
SFCError OpenEx(
    SFXAnsiStringConstRef path   // the path to the file of interest 
    SInt32 flags                 // bitwise or of one or more FS_O_* flags
);

Argument

path

the path to the file of interest

flags

The nFlags parameter is specified by exactly one of the following:

FS_O_RDONLY - open for read-only access
FS_O_WRONLY - open for write-only access
FS_O_RDWR - open for read-write access

bit-wise-or'd with zero or more of the following:

FS_O_CREAT - create the file if it does not exist
FS_O_EXCL - create the file only if it does not exist
FS_O_TRUNC - truncate the file to zero size after open
FS_O_APPEND - write operations will occur at the end of the file

Often, more than one flag will be specified, for example:

FS_O_WRONLY|FS_O_CREAT|FS_O_TRUNC - open a file for writing; create it if it does not exist; else truncate it to zero size

Not all combinations of flags are valid, for example:

FS_O_RDONLY|FS_O_TRUNC - can't truncate a read-only file FS_O_RDWR|FS_O_EXCL - exclusive requires create

Return value

Returns AEE_SUCCESS if the operation was successful. Otherwise returns a valid BREW-defined error code.

Description

See SFBFileSystem::Access() for a description of the privileges required to read and/or write paths.

Reference

BREW API IFilePort_OpenEx | SFBFileSystem::Access

SFBFilePort::Read

Reads bytes from a file currently open for reading.

[ public ]
SFCError Read(
    VoidPtr buffer   // where the bytes read should end up 
    SInt32 size      // how many bytes to attempt to read 
);

[ public ]
SFCError Read(
    SFXBufferPtr buffer   // where the bytes read should end up 
);

Return value

Returns the number of bytes read for a successful operation. Note that this may be less than the number of bytes requested.

A zero return value indicates end of file (EOF). Returns IPORT_ERROR otherwise;

the specific BREW-defined error code may be obtained via SFBFilePort::GetLastError().

Description

The bytes will be read at the current file point. The resulting file point will be advanced by the number of bytes read.

Reference

BREW API IFilePort_Read | SFBFilePort::GetLastError

SFBFilePort::Rewind

This function is the same as SFBFilePort::Seek() with nOffset equal to zero and nWhence equal to FS_SEEK_SET.

[ public ]
SFCError Rewind(Void);

Reference

BREW API IFilePort_Rewind | SFBFilePort::Seek

SFBFilePort::Seek

Reposition the file point in an open file.

[ public ]
SFCError Seek(
    SInt32 offset   // offset from whence; may be negative 
    SInt32 whence   // starting point for nOffset (FS_SEEK_*) 
);

Return value

Returns the new file point for a successful operation. Returns IPORT_ERROR otherwise; the specific BREW-defined error code may be obtained via SFBFilePort::GetLastError().

Description

The offset may be negative. The starting point may be one of the following:

FS_SEEK_SET - the start of the file
FS_SEEK_CUR - the current file point
FS_SEEK_END - the end of the file

The combination of offset and starting point may not result in a point that is before the beginning of the file.

The new point may be after the end of the file. However, seeking past the end does not grow the file; new bytes must be written to grow the file. Any resulting hole in the file will be read as a sequence of zero valued bytes.

Reference

BREW API IFilePort_Seek

SFBFilePort::Stat

Obtains information about an open file.

[ public ]
SFCError Stat(
    FSStat * buffer   // pointer to a struct FSStat, which is to be filled in 
    SInt32 size       // the size of buffer
);

Description

Common error codes: AEE_EBADSTATE: SFBFilePort is not open

Reference

BREW API IFilePort_Stat

SFBFilePort::StatVFS

Obtains information about the virtual file system containing an open file.

[ public ]
SFCError StatVFS(
    FSStatVFS * buffer   // pointer to a struct FSStatVFS, which is to be filled in 
    SInt32 size          // the size of buffer
);

Return value

Returns AEE_SUCCESS if the operation was successful. Otherwise returns a valid BREW-defined error code.

Description

Common error codes: AEE_EBADSTATE: SFBFilePort is not open

Reference

BREW API IFilePort_StatVFS

SFBFilePort::Truncate

Truncate a file to the specified length.

[ public ]
SFCError Truncate(
    SInt32 length   // the new length for the file
);

Return value

Returns AEE_SUCCESS if the operation was successful. Otherwise returns a valid BREW-defined error code.

Description

If the size of the file previously exceeded length, the extra data shall no longer be available to reads on the file.

If the file previously was smaller than this size, the extended area shall appear as if it were zero-filled. The value of the seek pointer shall not be modified.

Common error codes:

AEE_EBADSTATE: SFBFilePort is not open
AEE_EPRIVLEVEL: file is not open for writing

Reference

BREW API IFilePort_Truncate