Functions

Q3FSRefStorage_Get

( TQ3Status ) Q3FSRefStorage_Get (
    TQ3StorageObject storage,
    FSRef *fr
);

Discussion

Find the FSRef associated with an FSRef storage object.

Parameter Descriptions

storage
The FSSpec storage object to examine.

fr
On output, a file reference.

function result: Success or failure of the operation.

Q3FSRefStorage_New

( TQ3StorageObject ) Q3FSRefStorage_New (
    const FSRef *fr
);

Discussion

Create a storage object associated with a Mac file reference.

Given a valid FSRef structure, Quesa creates a storage object. The file should exist, but should not be open.

An FSSpec storage object is the same type of object as an FSRef storage object, hence the FSRef and FSSpec storage APIs can be used interchangeably.

Parameter Descriptions

fr
A valid file reference.

function result: The new storage object.

Q3FSRefStorage_Set

( TQ3Status ) Q3FSRefStorage_Set (
    TQ3StorageObject storage,
    const FSRef *fr
);

Discussion

Change the file reference for an FSRef storage object.

The storage must be closed at the time you call this.

Parameter Descriptions

storage
The FSRef storage object to modify.

fr
The new file reference.

function result: Success or failure of the operation.

Q3FSSpecStorage_Get

( TQ3Status ) Q3FSSpecStorage_Get (
    TQ3StorageObject storage,
    FSSpec *fs
);

Discussion

Find the FSSpec associated with an FSSpec storage object.

Parameter Descriptions

storage
The FSSpec storage object to examine.

fs
On output, a file system specification.

function result: Success or failure of the operation.

Q3FSSpecStorage_New

( TQ3StorageObject ) Q3FSSpecStorage_New (
    const FSSpec *fs
);

Discussion

Create a storage object associated with a Mac file specification.

Given a valid FSSpec structure, Quesa creates a storage object. The file should exist, but should not be open.

An FSSpec storage object is the same type of object as an FSRef storage object, hence the FSRef and FSSpec storage APIs can be used interchangeably.

Parameter Descriptions

fs
A valid file system specification.

function result: The new storage object.

Q3FSSpecStorage_Set

( TQ3Status ) Q3FSSpecStorage_Set (
    TQ3StorageObject storage,
    const FSSpec *fs
);

Discussion

Change the file specification for an FSSpec storage object.

The storage must be closed at the time you call this.

Parameter Descriptions

storage
The FSSpec storage object to modify.

fs
The new file system specification.

function result: Success or failure of the operation.

Q3HandleStorage_Get

( TQ3Status ) Q3HandleStorage_Get (
    TQ3StorageObject storage,
    Handle *handle,
    TQ3Uns32 *validSize
);

Discussion

Get information about a Handle storage object.

Parameter Descriptions

storage
The storage object.

handle
On output, the Handle associated with the storage.

validSize
On output, the valid size in bytes of the storage.

function result: Success or failure of the operation.

Q3HandleStorage_New

( TQ3StorageObject ) Q3HandleStorage_New (
    Handle handle,
    TQ3Uns32 validSize
);

Discussion

Create a Handle storage object.

Create a storage object that stores data in a Macintosh memory Handle. If you pass NULL for the Handle, Quesa internally allocates a Handle of the given size, and disposes the Handle when the storage object is disposed.

Parameter Descriptions

handle
An existing Handle, or NULL.

validSize
The size of the valid date in the given Handle, or the desired size if the Handle is NULL.

function result: The new storage object, or NULL on failure.

Q3HandleStorage_Set

( TQ3Status ) Q3HandleStorage_Set (
    TQ3StorageObject storage,
    Handle handle,
    TQ3Uns32 validSize
);

Discussion

Set information about a Handle storage object.

Sets the buffer location and size of a Handle storage object. If you pass NULL for the Handle, Quesa internally allocates a Handle of the given size, and disposes the Handle when the storage object is disposed.

Parameter Descriptions

storage
The storage object.

handle
A Mac Handle to be associated with the storage, or NULL.

validSize
Size in bytes of the specified buffer.

function result: Success or failure of the operation.

Q3MacintoshStorage_Get

( TQ3Status ) Q3MacintoshStorage_Get (
    TQ3StorageObject storage,
    TQ3Int16 *fsRefNum
);

Discussion

Get the file reference number associated with the storage.

Parameter Descriptions

storage
The storage object.

fsRefNum
On output, the file reference number of the file associated with the storage.

function result: Success or failure of the operation.

Q3MacintoshStorage_GetType

( TQ3ObjectType ) Q3MacintoshStorage_GetType (
    TQ3StorageObject storage
);

Discussion

Get a derived type of a Mac storage object, currently either kQ3MacintoshStorageTypeFSSpec or kQ3ObjectTypeInvalid.

Parameter Descriptions

storage
The storage object.

function result: The object type.

Q3MacintoshStorage_New

( TQ3StorageObject ) Q3MacintoshStorage_New (
    TQ3Int16 fsRefNum
);

Discussion

Create a Macintosh storage object.

This creates a storage object whose data is stored in a file, specified by a Mac file reference number for an open file. The specified file must remain open as long as you use the storage object, and it is your responsibility to close the file later.

Parameter Descriptions

fsRefNum
A file reference number for an open data fork of a Mac file.

function result: The new storage object.

Q3MacintoshStorage_Set

( TQ3Status ) Q3MacintoshStorage_Set (
    TQ3StorageObject storage,
    TQ3Int16 fsRefNum
);

Discussion

Change the file reference number associated with a Mac storage.

This cannot be used when the storage is open.

Parameter Descriptions

storage
The storage object.

fsRefNum
A file reference number for an open data fork of a Mac file.

function result: Success or failure of the operation.

Q3MemoryStorage_GetBuffer

( TQ3Status ) Q3MemoryStorage_GetBuffer (
    TQ3StorageObject storage,
    unsigned char **buffer,
    TQ3Uns32 *validSize,
    TQ3Uns32 *bufferSize
);

Discussion

Get the data of a memory storage object.

Gets a pointer to the data of a memory storage object without copying. The pointer may become invalid if later storage operations cause the buffer to be reallocated.

Each of the output parameters may be NULL if you don't need that information.

Parameter Descriptions

storage
The storage object.

buffer
On output, receives a pointer to the actual data of the storage.

validSize
On output, the number of valid metafile data bytes in the storage object.

bufferSize
On output, the size of the buffer in bytes.

function result: Success or failure of the operation.

Q3MemoryStorage_GetType

( TQ3ObjectType ) Q3MemoryStorage_GetType (
    TQ3StorageObject storage
);

Discussion

Get the type of a memory storage object.

Returns the sub-type of a memory storage object, currently either kQ3MemoryStorageTypeHandle or kQ3ObjectTypeInvalid.

Parameter Descriptions

storage
The storage object.

function result: The type of memory storage, or kQ3ObjectTypeInvalid.

Q3MemoryStorage_New

( TQ3StorageObject ) Q3MemoryStorage_New (
    const unsigned char *buffer,
    TQ3Uns32 validSize
);

Discussion

Create a memory storage object.

Creates a memory storage object using memory that is maintained internally by Quesa. If you pass a buffer of data, that data will be copied to the storage object's private memory

Parameter Descriptions

buffer
Pointer to a buffer in memory, or NULL.

validSize
Number of bytes of data in the buffer. If you passed NULL for the buffer, this number serves as the initial size and grow size of the internally allocated buffer. If you passed NULL for buffer and 0 for validSize, then Quesa uses a default grow size.

function result: The new storage object.

Q3MemoryStorage_NewBuffer

( TQ3StorageObject ) Q3MemoryStorage_NewBuffer (
    unsigned char *buffer,
    TQ3Uns32 validSize,
    TQ3Uns32 bufferSize
);

Discussion

Create a memory storage object that uses a provided buffer.

Creates a memory storage object using a given buffer rather than by allocating Quesa memory.

Parameter Descriptions

buffer
Pointer to a buffer of data, or NULL.

validSize
Number of bytes of valid data in the provided buffer, or if buffer was NULL, the initial size and grow size of an internally-allocated buffer.

bufferSize
Size in bytes of the buffer.

function result: The new storage object.

Q3MemoryStorage_Set

( TQ3Status ) Q3MemoryStorage_Set (
    TQ3StorageObject storage,
    const unsigned char *buffer,
    TQ3Uns32 validSize
);

Discussion

Sets the data of a memory storage object.

Writes data to a storage object by copying data from a buffer. Whether or not the storage object owned its own memory before this call (i.e., whether it was created with Q3MemoryStorage_New or Q3MemoryStorage_NewBuffer), it will own its own memory afterward.

Parameter Descriptions

storage
The storage object.

buffer
Pointer to a buffer of data, or NULL.

validSize
Number of bytes to be copied from the buffer to the storage, or initial memory size if buffer was NULL.

function result: Success or failure of the operation.

Q3MemoryStorage_SetBuffer

( TQ3Status ) Q3MemoryStorage_SetBuffer (
    TQ3StorageObject storage,
    unsigned char *buffer,
    TQ3Uns32 validSize,
    TQ3Uns32 bufferSize
);

Discussion

Sets the data of a memory storage object.

Sets the data of a memory storage object to be stored in a given buffer.

Parameter Descriptions

storage
The storage object.

buffer
Pointer to a buffer of data, or NULL.

validSize
Number of valid bytes in the buffer, or if the buffer is NULL, the initial and grow size of an internally allocated buffer.

bufferSize
Size in bytes of the buffer.

function result: Success or failure of the operation.

Q3PathStorage_Get

( TQ3Status ) Q3PathStorage_Get (
    TQ3StorageObject theStorage,
    char *pathName
);

Discussion

Finds the path associated with a path storage object.

The path returned by this function could be up to 1024 bytes long. Be sure to allocate enough space for it.

This function is not available in QD3D.

Parameter Descriptions

theStorage
A path storage object.

pathName
On output, the path as a NULL-terminated string.

function result: Success or failure of the operation.

Q3PathStorage_New

( TQ3StorageObject ) Q3PathStorage_New (
    const char *pathName
);

Discussion

Creates a storage object of type kQ3StorageTypePath. This type of storage is associated with a file specified by a path name, and is intended to replace the poorly-named "Unix path" storage.

The exact format of permissible paths is platform-dependent. For example, in a Mac version of Quesa built with the Metrowerks Standard Library, the path is colon-separated and assumed to be in the system encoding.

This function is not available in QD3D.

Parameter Descriptions

pathName
A NULL-terminated pathname, as might be passed to fopen.

function result: Success or failure of the operation.

Q3PathStorage_Set

( TQ3Status ) Q3PathStorage_Set (
    TQ3StorageObject theStorage,
    const char *pathName
);

Discussion

Changes the path associated with a path storage object.

This function is not available in QD3D.

Parameter Descriptions

theStorage
A path storage object.

pathName
A NULL-terminated pathname.

function result: Success or failure of the operation.

Q3Storage_GetData

( TQ3Status ) Q3Storage_GetData (
    TQ3StorageObject storage,
    TQ3Uns32 offset,
    TQ3Uns32 dataSize,
    unsigned char *data,
    TQ3Uns32 *sizeRead
);

Discussion

Read some data from a storage object.

Returns some or all of the private data associated with a storage object. If the storage is associated with a file object, then the file must be open.

Parameter Descriptions

storage
The storage object.

offset
Starting offset of the data to be retrieved.

dataSize
Number of bytes of data to get.

data
Buffer to receive the data.

sizeRead
On output, number of bytes actually received.

function result: Success or failure of the operation.

Q3Storage_GetSize

( TQ3Status ) Q3Storage_GetSize (
    TQ3StorageObject storage,
    TQ3Uns32 *size
);

Discussion

Get the size of the data in a storage object.

Returns the number of bytes of data stored in the object. If the storage is a type associated with a file, the file must be open.

Parameter Descriptions

storage
The storage object.

size
On output, receives the size.

function result: Success or failure of the operation.

Q3Storage_GetType

( TQ3ObjectType ) Q3Storage_GetType (
    TQ3StorageObject storage
);

Discussion

Returns the type of a storage object.

Returns kQ3StorageTypeMemory, kQ3StorageTypeUnix, kQ3StorageTypeMacintosh, or kQ3StorageTypeWin32, provided that the object is a storage object.

Parameter Descriptions

storage
The storage object to test.

function result: The type of storage, or kQ3ObjectTypeInvalid.

Q3Storage_SetData

( TQ3Status ) Q3Storage_SetData (
    TQ3StorageObject storage,
    TQ3Uns32 offset,
    TQ3Uns32 dataSize,
    const unsigned char *data,
    TQ3Uns32 *sizeWritten
);

Discussion

Write some data to a storage object.

Write some data to a storage object, possibly extending the storage to accommodate the new data. If the storage is associated with a file object, then the file must be open.

Parameter Descriptions

storage
The storage object.

offset
The offset at which to begin writing new data.

dataSize
Number of bytes of data to be written.

data
Data to be written.

sizeWritten
On output, number of bytes actually written, normally the same as dataSize.

function result: Success or failure of the operation.

Q3UnixPathStorage_Get

( TQ3Status ) Q3UnixPathStorage_Get (
    TQ3StorageObject storage,
    char *pathName
);

Discussion

Get the path associated with a Unix path storage object

The path returned by this function could be up to 1024 bytes long. Be sure to allocate enough space for it.

Parameter Descriptions

storage
A Unix path storage object.

pathName
On output, a NULL-terminated path.

function result: Success or failure of the operation.

Q3UnixPathStorage_New

( TQ3StorageObject ) Q3UnixPathStorage_New (
    const char *pathName
);

Discussion

Create a storage object associated with a file system path.

The Quesa extension Q3PathStorage_New may be used in place of this.

Parameter Descriptions

pathName
A NULL-terminated file system path.

function result: The new storage object.

Q3UnixPathStorage_Set

( TQ3Status ) Q3UnixPathStorage_Set (
    TQ3StorageObject storage,
    const char *pathName
);

Discussion

Change the path associated with a Unix path storage object.

Parameter Descriptions

storage
A Unix path storage object.

pathName
A NULL-terminated file system path.

function result: Success or failure of the operation.

Q3Win32Storage_Get

( TQ3Status ) Q3Win32Storage_Get (
    TQ3StorageObject storage,
    HANDLE *hFile
);

Discussion

Get the file handle for a Win32 storage object.

Parameter Descriptions

storage
The storage object to query.

hFile
Receives the file handle.

function result: Success or failure of the operation.

Q3Win32Storage_New

( TQ3StorageObject ) Q3Win32Storage_New (
    HANDLE hFile
);

Discussion

This creates a storage object whose data is stored in a file, specified by a file HANDLE for an open file. The specified file must remain open as long as you use the storage object, and it is your responsibility to close the file later.

Parameter Descriptions

hFile
A valid file handle.

function result: The new storage object.

Q3Win32Storage_Set

( TQ3Status ) Q3Win32Storage_Set (
    TQ3StorageObject storage,
    HANDLE hFile
);

Discussion

Set the file handle for a Win32 storage object.

Parameter Descriptions

storage
The storage object to update.

hFile
The new file handle.

function result: Success or failure of the operation.