Documentation  |   Table of Contents   |  < Previous   |  Next >   |  Index

89    Unified Data Access Manager

Palm OS® Programmer's API Reference

Palm OS® 68K SDK

     

This chapter provides reference material for the Unified Data Access (UDA) Manager, which provides a mechanism for abstracting read and write access to different kinds of source and destination media, including memory and the Exchange Manager.

The Personal Data Interchange (PDI) reader and writer objects use UDA objects, and you must create UDA objects to use the PDI functions.

This chapter discusses the following topics:

The header file UDAMgr.h declares the Unified Data Access Manager API.

You use the UDA Manager in conjunction with the PDI library. For more information about the PDI library, see Chapter 88, "Personal Data Interchange Library."

Chapter 3, "Personal Data Interchange," in the Palm OS Programmer's Companion, vol. II, Communications, provides examples of using the UDA functions with the PDI library.

UDA Manager Data Structures ^TOP^

UDABufferSize Typedef ^TOP^

Purpose

The UDABufferSize type is a simple typedef that defines the size of buffers used with UDA read functions.

Prototype

typedef UInt16 UDABufferSize;

UDAObjectType Struct ^TOP^

Purpose

The UDAObjectType is the base class for all UDA objects, and defines the common properties of all of the objects.

Prototype

typedef struct UDAObjectTag {
UInt16 optionFlags;
UDADeleteFunction deleteF;
UDAControlFunction controlF;
} UDAObjectType;

Fields

optionFlags
Options for the object. This is a combination of values described in Object Option Flags.
deleteF
The delete function associated with this UDA object.
controlF
The control function associated with this UDA object.

UDAFilterType Struct ^TOP^

Purpose

The UDAFilterType represents UDA Filters, which take input from a UDA Reader or UDA Filter, perform some encoding or decoding operation, and output the data to a memory buffer.

Prototype

typedef struct UDAFilterTag {
UInt16 optionFlags;
UDADeleteFunction deleteF;
UDAControlFunction controlF;
UDAReadFunction readF;
UDAReaderType *upperReader;
} UDAFilterType;

Fields

optionFlags
Options for the object. This is a combination of values described in Object Option Flags.
deleteF
The delete function associated with this UDA object.
controlF
The control function associated with this UDA object.
readF
The read function associated with this UDA object.
upperReader
The UDAReaderType or UDAFilterType object that reads the data that this object outputs.

UDAReaderType Struct ^TOP^

Purpose

The UDAReaderType represents UDA Readers, which read input from a medium.

Prototype

typedef struct UDAReaderTag {
UInt16 optionFlags;
UDADeleteFunction deleteF;
UDAControlFunction controlF;
UDAReadFunction readF;
} UDAReaderType;

Fields

optionFlags
Options for the object. This is a combination of values described in Object Option Flags.
deleteF
The delete function associated with this UDA object.
controlF
The control function associated with this UDA object.
readF
The read function associated with this UDA object.

UDAWriterType Struct ^TOP^

Purpose

The UDAWriterType represents UDA Writers, which take data from a UDA Reader or UDA Filter and write the data to an output medium.

Prototype

typedef struct UDAWriterTag {
UInt16 optionFlags;
UDADeleteFunction deleteF;
UDAControlFunction controlF;
UDAWriteFunction initiateWriteF;
UDAFlushFunction flushF;
UDAReaderType *upperReader;
} UDAWriterType;

Fields

optionFlags
Options for the object. This is a combination of values described in Object Option Flags.
deleteF
The delete function associated with this UDA object.
controlF
The control function associated with this UDA object.
initiateWriteF
The write function associated with this UDA object.
flushF
The flush function associated with this UDA object.
upperReader
The UDAReaderType object that reads the data that this object writes.

UDA Manager Constants ^TOP^

This section describes the constants used with the UDA Manager, which include the following constant types:

Control Flags ^TOP^

Use the control flag constants to control UDA objects with the UDAControl() macro.

Constant

Value

Description

kUDAReinitialize

1

Used with the UDAControl() macro to reinitialize the UDA object.

Error Constants ^TOP^

At the time of this writing, there is only one error constant associated with the UDA object API.

Constant

Description

udaErrControl

Returned by the UDAControl() macro when the control parameter is not valid for the UDA object.

Object Option Flags ^TOP^

You use the object option flag constants to determine information about the internal state of UDA objects. Note that the UDAEndOfReader() and UDAMoreData() macros provide you with a convenient means of accessing this same information.

Constant

Value

Description

kUDAEndOfReader

1

Indicates that the UDA reader has reached the end of its data.

kUDAMoreData

2

Indicates that the UDA reader needs more space in the read buffer to do its work.

Miscellaneous Constants ^TOP^

Constant

Value

Description

kUDAZeroTerminatedBuffer

0xFFFF

Indicates that the buffer is a null-terminated string. Use this value when creating or reinitializing a UDAMemoryReader object.

UDA Manager Functions ^TOP^

UDAControl Function ^TOP^

Purpose

Applies controls to a UDA object.

Declared In

UDAMgr.h

Prototype

Err UDAControl (
   UDAObjectType*ioObjectP,
   UInt16parameter,
   va_args
)

Parameters

ioObjectP
A pointer to the UDAObjectType object that you want to control. This can be a UDAReaderType, a UDAFilterType, or a UDAWriterType object.
parameter
The control action that you want applied to the object.
va_args
Additional parameters, as required for the control and object type.

Returns

Returns errNone if no error, or udaErrorClass if the control parameter is not valid for the ioObjectP.

Comments

The UDAControl function applies a control action to a UDA object. You may need to supply additional parameters, depending on the object type and control parameter values.

The only control action defined in Palm OS 4.0 is kUDAReinitialize. You can use it as shown in Table 89.1.

L

Table 89.1  UDAControl actions

Object Type

Usage

Action

UDAExchangeReaderType

UDAControl(myExgRdr, kUDAReinitialize)

Does nothing

UDAExchangeWriterType

UDAControl(myExgWtr, kUDAReinitialize)

Does nothing

UDAMemoryReaderType

UDAControl(myMemRdr, kUDAReinitialize, bufferP, bufferSize)

Reinstalls a new buffer for the memory reader. See UDAMemoryReaderNew() for more information about the parameters.

Compatibility

Implemented only if 4.0 New Feature Set is present.

UDADelete Macro ^TOP^

Purpose

Deletes a UDA object.

Declared In

UDAMgr.h

Prototype

#define UDADelete (
   ioObjectP
)

Parameters

ioObjectP
A pointer to the UDAObjectType object that you want to delete. This can be a UDAReaderType, a UDAFilterType, or a UDAWriterType object.

Returns

Returns nothing.

Comments

The ioObjectP pointer is not valid after this macro completes.

Compatibility

Implemented only if 4.0 New Feature Set is present.

UDAEndOfReader Macro ^TOP^

Purpose

Tests if the end of the reader has been reached.

Declared In

UDAMgr.h

Prototype

#define UDAEndOfReader (
   ioReaderP
)

Parameters

ioReaderP
A pointer to a UDAReaderType object.

Returns

Returns true if the end of the reader referenced by ioReaderP has been reached, and false if not.

Comments

The end of the reader has been reached.

Compatibility

Implemented only if 4.0 New Feature Set is present.

UDAFilterJoin Macro ^TOP^

Purpose

Joins a filter with a reader.

Declared In

UDAMgr.h

Prototype

#define UDAFilterJoin (
   ioFilterP,
   newReaderP
)

Parameters

ioFilterP
A pointer to a UDAFilterType object.
newReaderP
A pointer to the UDAReaderType object with which you want the filter joined.

Returns

Returns nothing.

Comments

Each UDAFilterType object receives its data from the UDAReaderType object to which it is joined; this relationship is established when you create the filter object. You can use this macro to change the reader with which the filter is joined. Upon completion, the filter referenced by ioFilterP is joined with the reader referenced by newReaderP.

Compatibility

Implemented only if 4.0 New Feature Set is present.

UDAInitiateWrite Macro ^TOP^

Purpose

Causes the UDAWriterType object to read data and then write that data to output.

Declared In

UDAMgr.h

Prototype

#define UDAInitiateWrite (
   ioWriterP
)

Parameters

ioWriterP
A pointer to a UDAWriterType object.

Returns

Returns errNone if successful, and an error code if not.

Comments

When you use this macro, the ioWriterP reads data from the reader to which it is joined. It reads data until the reader is empty, and then writes the data to the output medium.

Compatibility

Implemented only if 4.0 New Feature Set is present.

UDAMoreData Macro ^TOP^

Purpose

Tests if there is more data available to read, but not enough room in the buffer to read it in.

Declared In

UDAMgr.h

Prototype

#define UDAMoreData (
   ioReaderP
)

Parameters

ioReaderP
A pointer to a UDAReaderType object.

Returns

Returns true if there is more data available for the reader and false if there is no more data available.

Comments

You can use this macro with UDAReaderType objects to determine if there is more data waiting to read. This can happen when the reader's buffer is full.

Compatibility

Implemented only if 4.0 New Feature Set is present.

UDARead Macro ^TOP^

Purpose

Uses the specified UDAReaderType object to read data from the input source and place that data into the specified buffer.

Declared In

UDAMgr.h

Prototype

#define UDARead (
   ioReaderP,
   bufferToFillP,
   bufferSize,
   errorP
)

Parameters

ioReaderP
A pointer to a UDAReaderType object that performs the read.
bufferToFillP
A pointer to the buffer into which data is placed.
bufferSize
The size of the buffer, in bytes.
errorP
A pointer to an Err value that represents the result of the read operation; if the operation is successful, the value is set to errNone.

Returns

Returns the number of bytes that were actually read. This value can be less than or equal to the value of bufferSize.

Comments

The reader reads from the input source associated with the reader object and places the data into the specified buffer, reading no more than bufferSize bytes of data.

Compatibility

Implemented only if 4.0 New Feature Set is present.

UDAWriterFlush Macro ^TOP^

Purpose

Flushes the buffer used by the UDAWriterType object.

Declared In

UDAMgr.h

Prototype

#define UDAWriterFlush (
   ioWriterP
)

Parameters

ioWriterP
A pointer to a _UDAWriterType object.

Returns

Returns errNone if successful, and an error code if not.

Comments

You can use this macro to flush any data remaining in the buffer of the writer object referenced by ioWriterP. This causes any data in the buffer to be sent to the output medium.

Compatibility

Implemented only if 4.0 New Feature Set is present.

UDAWriterJoin Macro ^TOP^

Purpose

Joins a writer object to a different reader object.

Declared In

UDAMgr.h

Prototype

#define UDAWriterJoin (
   ioWriterP,
   newReaderP
)

Parameters

ioWriterP
A pointer to a UDAWriterType object.
newReaderP
A pointer to the UDAReaderType object with which you want the writer joined.

Returns

Returns nothing.

Comments

Each UDAWriterType object receives its data from the UDAReaderType object to which it is joined; this relationship is established when you create the writer object. You can use this macro to change the reader with which the writer is joined. Upon completion, the writer referenced by ioWriterP is joined with the reader referenced by newReaderP.

Compatibility

Implemented only if 4.0 Feature Set is present.

UDA Object Creation Functions ^TOP^

UDAExchangeReaderNew Function ^TOP^

Purpose

Creates a new UDAReaderType object that you can use to read data from an Exchange Manager socket.

Declared In

UDAMgr.h

Prototype

UDAReaderType *UDAExchangeReaderNew(
   ExgSocketPtrsocket
)

Parameters

socket
A pointer to an ExgSocketType structure that describes the connection.

Returns

Returns a pointer to the newly created UDAReaderType object, or NULL if the reader could not be created.

Comments

Use this function to create a UDA Reader object that takes input from an Exchange Manager socket.

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

ExgSocketType

UDAExchangeWriterNew Function ^TOP^

Purpose

Creates a new UDAWriterType object that you can use to write data to an Exchange Manager socket.

Declared In

UDAMgr.h

Prototype

UDAWriterType *UDAExchangeWriterNew(
   ExgSocketPtrsocket,
   UDABufferSizebufferSize
)

Parameters

socket
A pointer to an ExgSocketType structure that describes the connection.
bufferSize
The size, in bytes, of the buffer for the new writer object.

Returns

Returns a pointer to the newly created UDA Writer, or NULL if the writer could not be created.

Comments

Use this function to create a UDA Writer object that sends output to an Exchange Manager socket.

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

ExgSocketType

UDAMemoryReaderNew Function ^TOP^

Purpose

Creates a new UDAReaderType object that you can use to read data from a memory buffer.

Declared In

UDAMgr.h

Prototype

UDAReaderType *UDAMemoryReaderNew(
   constUInt8*bufferP,
   UDABufferSizebufferSizeInBytes
)

Parameters

bufferP
A pointer to a buffer in memory from which data is read.
bufferSize
The size of the buffer, in bytes. If this value is equal to kUDAZeroTerminatedBuffer, bufferP must point to a null-terminated string buffer.

Returns

Returns a pointer to the newly created UDAReaderType object, or NULL if the reader could not be created.

Comments

Use this function to create a reader that takes input from memory.

Compatibility

Implemented only if 4.0 New Feature Set is present.