|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
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. |
The UDAReaderType represents UDA Readers, which read input from a medium.
typedef struct UDAReaderTag { UInt16 optionFlags; UDADeleteFunction deleteF; UDAControlFunction controlF; UDAReadFunction readF; } UDAReaderType
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. |
The UDAWriterType represents UDA Writers, which take data from a UDA Reader or UDA Filter and write the data to an output medium.
typedef struct UDAWriterTag { UInt16 optionFlags; UDADeleteFunction deleteF; UDAControlFunction controlF; UDAWriteFunction initiateWriteF; UDAFlushFunction flushF; UDAReaderType* upperReader; } UDAWriterType
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. |
This section describes the constants used with the UDA Manager, which include the following constant types:
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. |
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. |
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 |
---|---|---|
kUDAZeroTerminatedBuffer |
0xFFFF |
Indicates that the buffer is a null terminated string. Use this value when creating or reinitializing a UDAMemoryReader object. |
Applies controls to a UDA object.
Err UDAControl (UDAObjectType* ioObjectP,
UInt16 parameter, va_args);
-> 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 errNone if no error, or udaErrorClass if the control parameter is not valid for the ioObjectP.
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 79.1.
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. |
Implemented only if 4.0 New Feature Set is present.
Macro that deletes a UDA object.
-> ioObjectP | A pointer to the UDAObjectType object that you want to delete. This can be a UDAReaderType, a UDAFilterType, or a UDAWriterType object. |
The ioObjectP pointer is not valid after this macro completes.
Implemented only if 4.0 New Feature Set is present.
Macro that tests if the end of the reader has been reached.
-> ioReaderP | A pointer to a UDAReaderType object. |
Returns true if the end of the reader referenced by ioReaderP has been reached, and false if not.
The end of the reader has been reached.
Implemented only if 4.0 New Feature Set is present.
Macro that joins a filter with a reader.
UDAFilterJoin (ioFilterP, newReaderP)
--> ioFilterP | A pointer to a UDAFilterType object. |
--> newReaderP | A pointer to the UDAReaderType object with which you want the filter joined. |
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.
Implemented only if 4.0 New Feature Set is present.
Macro that causes the UDAWriterType object to read data and then write that data to output.
-> ioWriterP | A pointer to a UDAWriterType object. |
Returns errNone if successful, and an error code if not.
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.
Implemented only if 4.0 New Feature Set is present.
Macro that tests if there is more data available to read, but not enough room in the buffer to read it in.
-> ioReaderP | A pointer to a UDAReaderType object. |
Returns true if there is more data available for the reader and false if there is no more data available.
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.
Implemented only if 4.0 New Feature Set is present.
Macro that uses the specified UDAReaderType object to read data from the input source and place that data into the specified buffer.
UDARead (ioReaderP, bufferToFillP, bufferSize,
errorP)
-> 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 the number of bytes that were actually read. This value can be less than or equal to the value of bufferSize.
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.
Implemented only if 4.0 New Feature Set is present.
Macro that flushes the buffer used by the UDAWriterType object.
-> ioWriterP | A pointer to a _UDAWriterType object. |
Returns errNone if successful, and an error code if not.
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.
Implemented only if 4.0 New Feature Set is present.
Macro that joins a writer object to a different reader object.
UDAWriterJoin (ioWriterP, newReaderP)
-> ioWriterP | A pointer to a UDAWriterType object. |
-> newReaderP | A pointer to the UDAReaderType object with which you want the writer joined. |
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.
Implemented only if 4.0 Feature Set is present.
Creates a new UDAReaderType object that you can use to read data from an Exchange Manager socket.
UDAReaderType* UDAExchangeReaderNew
(ExgSocketPtr socket);
-> socket | A pointer to an ExgSocketType structure that describes the connection. |
Returns a pointer to the newly created UDAReaderType object, or NULL if the reader could not be created.
Use this function to create a UDA Reader object that takes input from an Exchange Manager socket.
Implemented only if 4.0 New Feature Set is present.
Creates a new UDAWriterType object that you can use to write data to an Exchange Manager socket.
UDAWriterType* UDAExchangeWriterNew
(ExgSocketPtr socket, UDABufferSize bufferSize);
-> 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 a pointer to the newly created UDA Writer, or NULL if the writer could not be created.
Use this function to create a UDA Writer object that sends output to an Exchange Manager socket.
Implemented only if 4.0 New Feature Set is present.
Creates a new UDAReaderType object that you can use to read data from a memory buffer.
UDAReaderType* UDAMemoryReaderNew
(const UInt8* bufferP,
UDABufferSize bufferSizeInBytes);
-> 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 a pointer to the newly created UDAReaderType object, or NULL if the reader could not be created.
Use this function to create a reader that takes input from memory.
Implemented only if 4.0 New Feature Set is present.
|