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:
- UDA Manager Data Structures
- UDA Manager Constants
- UDA Manager Functions
- UDA Object Creation Functions
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
UDABufferSize Typedef
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
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
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
orUDAFilterType
object that reads the data that this object outputs.
UDAReaderType Struct
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
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
This section describes the constants used with the UDA Manager, which include the following constant types:
Control Flags
Use the control flag constants to control UDA objects with the UDAControl()
macro.
Used with the |
Error Constants
At the time of this writing, there is only one error constant associated with the UDA object API.
Returned by the |
Object Option Flags
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.
Indicates that the UDA reader has reached the end of its data. |
||
Indicates that the UDA reader needs more space in the read buffer to do its work. |
Miscellaneous Constants
Indicates that the buffer is a null-terminated string. Use this value when creating or reinitializing a |
UDA Manager Functions
UDAControl Function
Purpose
Applies controls to a UDA object.
Declared In
UDAMgr.h
Prototype
Err UDAControl ( UDAObjectType *ioObjectP, UInt16 parameter, va_args )
Parameters
-
→
ioObjectP
- A pointer to the
UDAObjectType
object that you want to control. This can be aUDAReaderType
, aUDAFilterType
, or aUDAWriterType
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.
Reinstalls a new buffer for the memory reader. See |
Compatibility
Implemented only if 4.0 New Feature Set is present.
UDADelete Macro
Purpose
Declared In
UDAMgr.h
Prototype
#define UDADelete ( ioObjectP )
Parameters
-
→
ioObjectP
- A pointer to the
UDAObjectType
object that you want to delete. This can be aUDAReaderType
, aUDAFilterType
, or aUDAWriterType
object.
Returns
Comments
The ioObjectP
pointer is not valid after this macro completes.
Compatibility
Implemented only if 4.0 New Feature Set is present.
UDAEndOfReader Macro
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
Purpose
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
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
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
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
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 toerrNone
.
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
Purpose
Flushes the buffer used by the UDAWriterType
object.
Declared In
UDAMgr.h
Prototype
#define UDAWriterFlush ( ioWriterP )
Parameters
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
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
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
UDAExchangeReaderNew Function
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( ExgSocketPtr socket )
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
UDAExchangeWriterNew Function
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( ExgSocketPtr socket, UDABufferSize bufferSize )
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
UDAMemoryReaderNew Function
Purpose
Creates a new UDAReaderType
object that you can use to read data from a memory buffer.
Declared In
UDAMgr.h
Prototype
UDAReaderType *UDAMemoryReaderNew( const UInt8 *bufferP, UDABufferSize bufferSizeInBytes )
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.