This chapter provides reference material for the Personal Data Interchange (PDI) library, which provides tools for reading and writing vObjects, including vCards and vCals. This chapter discusses the following topics:
The header file PdiLib.h
declares the Personal Data Interchange library API. The header file PdiConst.h
declares the constants that you use with the PDI library.
For information about how to use the functions and constants described in this chapter, see Chapter 6, "Personal Data Interchange."
PDI Library Data Structures
This section describes the data structures used with the PDI library functions.
PdiDictionary Typedef
Purpose
The PdiDictionary
type is a simple typedef that represents an internal, binary object.
Prototype
typedef uint8_t PdiDictionary;
PdiReaderType Struct
Purpose
The PdiReaderType
data structure represents a PDI reader object, which you use to read data from an input stream.
Prototype
typedef struct PdiReaderTag { Err16 errorLowWord; uint16_t encoding; uint8_t fieldNum; CharEncodingType charset; uint16_t written; uint16_t property; uint16_t propertyValueType; uint16_t parameter; uint16_t padding1; uint32_t parameterPairs[8]; uint16_t customFieldNumber; uint16_t padding2; void *appData; uint16_t pdiRefNum; uint16_t events; char *groupName; char *propertyName; char *parameterName; char *parameterValue; char *propertyValue; } PdiReaderType
Fields
-
errorLowWord
- The most recent error.
-
encoding
- The type of encoding for the property value.
-
fieldNum
- The current field number.
-
charset
- The character set of the property value.
-
written
- The number of characters that have currently been written to the buffer.
-
property
- The ID of the current property.
-
propertyValueType
- The value type of the current property value.
-
parameter
- The ID of the most recently parsed parameter name.
-
padding1
- Padding; not used.
-
parameterPairs
- An integer array with bits set for each parameter value that has been parsed for the current property value.
-
customFieldNumber
- The number of the custom field parsed by the reader for the current property. Custom fields are used in the Address Book.
-
padding2
- Padding; not used.
-
appData
- Application-dependent data field.
-
pdiRefNum
- The library reference number associated with this reader. This is no longer used for ARM code development, but is kept for compatibility with code written for the 68K environment.
-
events
- The mask of events handled by the reader in its most recent operation. This is a combination of some number of the event constants described in Reader Event Constants.
-
groupName
- The group name for the current property.
-
propertyName
- The name of the current property.
-
parameterName
- The name of the current parameter.
-
parameterValue
- The value of the current parameter.
-
propertyValue
- The current property value string.
PdiWriterType Struct
Purpose
The PdiWriterType
data structure represents a PDI writer object, which you use to write data to an output stream.
Prototype
typedef struct _PdiWriter { Err16 errorLowWord; uint16_t encoding; CharEncodingType charset; uint8_t padding1[2]; uint32_t reserved; void *appData; uint16_t pdiRefNum; uint16_t padding2; } PdiWriterType
Fields
-
errorLowWord
- The most recent error.
-
encoding
- The type of encoding for the property value.
-
charset
- The character set of the property value.
-
padding1
- Padding; not used.
-
reserved
- Reserved for future use.
-
appData
- Application-dependent data field.
-
pdiRefNum
- The library reference number associated with this reader. This is no longer used for native code development, but is kept for compatibility with code written for the 68K environment.
-
padding2
- Padding; not used.
PDI Library Constants
This section describes the constants used in the PDI library, which include the following constant types:
- Buffer Management Constants
- Encoding Type Constants
- Error Code Constants
- Parameter Name Constants
- Parameter Value Constants
- Property Name Constants
- Property Type Constants
- Property Value Field Constants
- Property Value Format Constants
- Reader and Writer Options Constants
- Reader Event Constants
- Value Type Constants
Buffer Management Constants
You use the buffer management constants to determine how buffers are managed in the PDI reader.
Indicates that the buffer can be automatically resized by the PDI library. |
||
The default maximum buffer size, in bytes. You can change the maximum size of a reader's buffer by calling the |
||
The default number of bytes by which the input buffer is grown when the PDI library performs automatic resizing. You can change the delta amount of a reader's buffer by calling |
Encoding Type Constants
You use the encoding type constants to specify the type of encoding used in a vObject reader or writer.
Error Code Constants
The PDI library functions return the error code constants shown in the following table to indicate their status.
Parameter Name Constants
The PdiConst.h
file defines several parameter name constants that you can use to specify the name of a parameter in functions that use parameter names. The parameter name constants have the following format:
kPdiPAN_parameterName
where parameterName is replaced by a parameter name.
The following table shows examples of parameter name constants. For a complete list, see the PdiConst.h
file.
Parameter Value Constants
The PdiConst.h
file defines several parameter value constants that you can use to specify the name and value of a parameter in functions that use name and value pairs. The parameter value constants have the following format:
kPdiPAV_parameterName_parameterValue
where parameterName is replaced by a parameter name and parameterValue is replaced by a parameter value.
The following table shows examples of parameter value constants. For a complete list, see the PdiConst.h
file.
Property Name Constants
The PdiConst.h
file defines several property name constants that you can use to specify the name of a PDI property in functions that use property names. The property name constants have the following format:
kPdiPRN_propertyName
where propertyName is replaced by a property name.
The following table shows examples of property name constants. For a complete list, see the PdiConst.h
file.
Property Type Constants
You use the property type constants defined in PdiConst.h
to specify the data type of a property.
Property Value Field Constants
The PdiConst.h
file defines several property value field constants that you can use to specify the position of a PDI property value field in functions that use fields. The property value field constants have the following format:
kPdiPVF_propertyValueField
where propertyValueField is replaced by a property value field name.
The following table shows examples of property name constants. For a complete list, see the PdiConst.h
file.
Property Value Format Constants
Some properties have structured values, which are values that contain multiple fields. These fields are typically separated by commas or semicolons in the vObject input or output stream. You use the property value format constants with the PdiReadPropertyField()
and PdiWritePropertyStr()
functions to specify how to handle fields in a structured value.
There are no fields in the property value; |
||
Fields are separated with comma (" |
||
Fields are separated with semicolon (" |
||
The parser decides the property value format, based on the property name. |
||
Fields are separated with comma characters; |
||
Fields are separated with semicolon characters; |
Reader and Writer Options Constants
You use the reader and writer option constants to control how the PDI reader (parser) reads values from the input stream or to control how the PDI writer (generator) writes values to the output stream.
Enables folding of properties in the output stream. Folding is a mechanism for breaking long lines to allow them to be transmitted without change. If you specify this flag, the PDI library folds long lines. Note that folding is not compatible with versions of the Palm OS® earlier than 4.0. Also note that other encoding formats, including quoted-printable and Base 64, define their own mechanisms for splitting long lines. |
||
Enables quoted-printable encoding in the output stream and makes it the default encoding. This is an encoding format for non-ASCII values. You must have this enabled for compatibility with versions of the Palm OS earlier than 4.0. If you do not specify this option, the default encoding is Base 64. |
||
For compatibility with versions of the Palm OS earlier than 4.0. You must enable this for compatibility with versions of the Palm OS earlier than 4.0. However, some non-Palm PDI software does not support this format. For more information about compatibility with earlier versions of the Palm OS, see "Format Compatibility." |
||
This is a combination of |
||
Enables base 64 encoding in the output stream, and tells the PDI writer to output " Note: the vCard 3.0 standard has replaced the earlier |
||
Specifies that the PDI reader is open to all formats, including Palm and others. |
||
Bypasses the default character encoding for reading and writing. |
Reader Event Constants
The PDI reader event constants specify the events that the reader has handled during the current read operation. The event values are combined together and stored in the events
field of the PDI reader object. You can use them to test whether the reader handled a certain event.
Value Type Constants
You can use the following constants to specify data typing information for the PdiWritePropertyBinaryValue()
, PdiWritePropertyFields()
, and PdiWritePropertyValue()
functions.
PDI Library Functions
PdiDefineReaderDictionary Function
Purpose
Installs a new custom dictionary for use with a PDI reader object.
Declared In
PdiLib.h
Prototype
PdiDictionary *PdiDefineReaderDictionary ( PdiReaderType *ioReader
, PdiDictionary *dictionary
, BooleandisableMainDictionary
)
Parameters
-
→
ioReader
- The PDI reader object with which to associate the dictionary. This object must have previously been created by a call to the
PdiReaderNew()
function. -
→
dictionary
- A pointer to a dictionary object that was created by the . The dictionary object is an array of binary data.
-
→
disableMainDictionary
- If
true
, the main reader dictionary is disabled, and only this new dictionary is searched for terms; iffalse
, the new dictionary supplements the main dictionary.
Returns
Returns a pointer to the previously installed custom dictionary, or NULL
if there was not a previously installed custom dictionary.
Comments
This function installs a dictionary for use with the ioReader
object. The dictionary contains the syntax for extensions or replacements of the PDI properties about which the PDI reader knows. The reader knows about properties specified in one of the vObject standards, including the vCard or vCal standards.
You can uninstall the current custom dictionary by specifying NULL
as the value of the dictionary
parameter,
PdiDefineResizing Function
Purpose
Defines the sizing information to use when automatically resizing a buffer. PDI reader objects read information from the input stream into a buffer and automatically adjust the buffer size as required.
Declared In
PdiLib.h
Prototype
status_t PdiDefineResizing ( PdiReaderType *ioReader
, uint16_tdeltaSize
, uint16_tmaxSize
)
Parameters
-
→
ioReader
- The PDI reader object, which was created by a previous call to the
PdiReaderNew()
function. -
→
deltaSize
- The number of bytes by which to grow the buffer when it needs resizing.
-
→
maxSize
- The maximum allowable size for the buffer.
Returns
Returns errNone
if successful, and an error code if not successful.
Comments
This function redefines the values to use when resizing a buffer. It does not perform any other actions.
The resizing values are used if your reader runs out of buffer space when storing input data during the processing of a property value. If possible, the reader resizes its internal buffer, using the values that you supply in this function.
The default resizing values apply if you do not call this function. The default values are:
PdiDefineWriterDictionary Function
Purpose
Installs a new custom dictionary for use with a PDI writer object.
Declared In
PdiLib.h
Prototype
PdiDictionary *PdiDefineWriterDictionary ( PdiWriterType *ioWriter
, PdiDictionary *dictionary
, BooleandisableMainDictionary
)
Parameters
-
→
ioWriter
- The PDI writer object with which to associate the dictionary. This object must have previously been created by a call to the
PdiWriterNew()
function. -
→
dictionary
- A pointer to a dictionary object that was created by the . The dictionary object is an array of binary data.
-
→
disableMainDictionary
- If
true
, the main dictionary is disabled, and only this new dictionary is searched for terms; iffalse
, the new dictionary supplements the main dictionary.
Returns
Returns a pointer to the previously installed custom dictionary, or NULL
if there was not a previously installed custom dictionary.
Comments
This function installs a dictionary for use with the ioWriter
object. The dictionary contains the syntax for extensions or replacements of the PDI properties about which the PDI writer knows. The writer knows about properties specified in one of the vObject standards, including the vCard or vCal standards.
You can uninstall the current custom dictionary by specifying NULL
as the value of the dictionary
parameter,
PdiEnterObject Function
Purpose
Tells the PDI library to enter into a recursively-defined object.
Declared In
PdiLib.h
Prototype
status_t PdiEnterObject (
PdiReaderType *ioReader
)
Parameters
-
→
ioReader
- The PDI reader object, which was created by a previous call to the
PdiReaderNew()
function.
Returns
Returns errNone
if successful, and an error code if not successful.
Comments
Some vObjects recursively define other vObjects. Your application can choose whether or not to enter and parse the recursively defined objects.
If you want to parse the nested object definition, you need to call this function; otherwise, all of the properties of the nested object are skipped when the next call is made to the PdiReadProperty()
or PdiReadPropertyName()
functions.
Call this function after a BEGIN_VObject
statement of the nested object has been parsed.
PdiLibClose Function
Purpose
Decrements a reference count of PdiLibOpen()
calls.
Declared In
PdiLib.h
Prototype
status_t PdiLibClose (
void
)
Parameters
Returns
Returns 0 if no other application uses the library. Returns pdiErrCloseFailed
if the library is in use by another application.
Comments
This function is no longer needed for ARM code development, but is kept for compatibility with code written for the 68K environment.
See Also
PdiLibOpen Function
Purpose
Increments a reference count of PdiLibOpen()
calls.
Declared In
PdiLib.h
Prototype
status_t PdiLibOpen (
void
)
Parameters
Returns
Comments
This function is no longer needed for ARM code development, but is kept for compatibility with code written for the 68K environment.
See Also
PdiParameterPairTest Macro
Purpose
Determines if the reader has already parsed the specified parameter value or name-value pair.
Declared In
PdiLib.h
Prototype
#define PdiParameterPairTest (reader
,pair
)
Parameters
-
→
reader
- The PDI reader object, which was created by a previous call to the
PdiReaderNew()
function. -
→
pair
- The ID of the parameter. This must be one of the Parameter Value Constants.
Returns
Returns true
if the specified parameter name-value pair has been parsed for the current property, and false
if not.
Comments
Some vObject generators do not specify the parameter name if the name is considered evident from the context. This means that both of the following constructs are considered proper:
The PdiParameterPairTest
macro returns true
if the value has been parsed in either format. For example,
PdiParameterPairTest
(reader, kPdiPAV_TYPE_WORK)
returns true for either of the following:
PdiReaderDelete Function
Purpose
Delete a PDI reader object that is associated with the specified library number.
Declared In
PdiLib.h
Prototype
void PdiReaderDelete (
PdiReaderType **ioReader
)
Parameters
-
↔
ioReader
- A pointer to the PDI reader object, which was created by a previous call to the
PdiReaderNew()
function.
Returns
Comments
This function deletes the UDAReader
object associated with the reader object and frees the memory that was allocated for the reader object. The ioReader
parameter is set to NULL
.
See Also
PdiReaderNew Function
Purpose
Create and initialize a new PDI reader object for use with the specified PDI library number.
Declared In
PdiLib.h
Prototype
PdiReaderType *PdiReaderNew ( UDAReaderType *input
, uint16_tversion
)
Parameters
-
→
input
- The Unified Data Access (UDA) input object associated with the reader.
-
→
version
- Options to control the parsing behavior of the reader. You can use a combination of the Reader and Writer Options Constants.
Returns
Returns a pointer to the new PDI reader object. Returns NULL
if the reader cannot be created.
Comments
The current implementation of the PdiReaderNew()
function does not make use of the optionFlags
settings because the reader knows how to adapt itself to all of the supported formats. The options will be used in future versions.
The input
value is a UDA object for reading data from an input stream that can be connected to various data sources. For example, you can use a UDAExchangeReader
to read data from the Exchange Manager, and you can use a UDAStringReader
to read data from a string. For more information about the UDA Manager, see Chapter 8, "Unified Data Access Manager Reference."
See Also
PdiReaderDelete()
, PdiWriterNew()
PdiReadParameter Function
Purpose
Read a single parameter name and its value from an input stream.
Declared In
PdiLib.h
Prototype
status_t PdiReadParameter (
PdiReaderType *ioReader
)
Parameters
-
→
ioReader
- The PDI reader object, which was created by a previous call to the
PdiReaderNew()
function.
Returns
-
0
- The parameter and its value were read successfully.
-
kPdiReadError
- The parameter and its value could not be successfully read from the input stream.
Comments
This function initializes the parameterName
and parameter
fields of the ioReader
object.
This function sets the appropriate bits in the reader's parameterValues
field if the parameter name is recognized.
If you are reading a property, it's parameters, and its values individually, you should call PdiReadPropertyName()
before calling PdiReadParameter()
one or more times to read parameters. Then call PdiReadPropertyField()
to read the property value fields.
See Also
PdiReadProperty Function
Purpose
Read the next property and its parameters from the input stream.
Declared In
PdiLib.h
Prototype
status_t PdiReadProperty (
PdiReaderType *ioReader
)
Parameters
-
→
ioReader
- The PDI reader object, which was created by a previous call to the
PdiReaderNew()
function.
Returns
Returns errNone
if successful. Returns kPdiReadError
if an error occurs.
Comments
The PdiReadProperty()
function reads a property name and its parameters, by reading until it encounters the PDI ":
" separator character.
This function looks each name up in the properties dictionary, and sets the appropriate bit in the ioReader
object structure to indicate that property-parameter pair has been read. The properties dictionary stores information about properties that are considered well known, as described in "The PDI Library Properties Dictionary."
To read a property, you call PdiReadProperty()
, followed by a call or calls to the PdiReadPropertyField()
function to read the property value. For more information, see "Reading Properties."
See Also
PdiReaderNew()
, PdiReadPropertyField()
, PdiReadPropertyName()
, PdiReadParameter()
PdiReadPropertyField Function
Purpose
Read one field of a property value. The property value can be structured to contain multiple fields that are separated by commas or semicolons.
Declared In
PdiLib.h
Prototype
status_t PdiReadPropertyField ( PdiReaderType *ioReader
, char **bufferPP
, uint16_tbufferSize
, uint16_treadMode
)
Parameters
-
→
ioReader
- The PDI reader object, which was created by a previous call to the
PdiReaderNew()
function. -
↔
bufferPP
- A pointer to a pointer to the buffer into which the field characters are stored. Set this value to
NULL
to allow the PDI library to manage it. - Note that the PDI library may need to resize the buffer; thus, the value of this parameter might change.
-
→
bufferSize
- The size, in bytes, of the input buffer for reading the field.
- You can use the
PdiResizableBuffer
constant to specify that the PDI Library can automatically resize the buffer as required. - If you do not specify the
PdiResizableBuffer
value, then the PDI library assumes thatbuffer
cannot be moved, and that its size is fixed. -
→
readMode
- The format of the fields in the property value. Use one of the Property Value Format Constants.
Returns
-
0
- The field was read successfully.
-
kPdiNoMoreFieldsError
- There are no more fields to read because the entire value has already been read.
-
kPdiMoreCharsError
- The buffer is not large enough to store the entire field.
Comments
The value returned in the buffer
is terminated with the "\0
" character.
If the field is an empty string, the buffer is erased from memory, and the value of buffer
is set to NULL
.
If you specify kPdiResizableBuffer
for the value of the bufferSize
parameter, and the buffer needs more space, PdiReadPropertyField()
resizes the buffer for you, which may cause the value of buffer
to be modified.
This function initializes the propertyValue
and fieldNum
fields of the ioReader
object.
To read a property, you usually call the PdiReadProperty()
function, followed by a call or calls to PdiReadPropertyField()
to read the property value. For more information, see "Reading Properties."
See Also
PdiReaderNew()
, PdiReadProperty()
, PdiReadPropertyName()
, PdiReadParameter()
PdiReadPropertyName Function
Purpose
Read a property name from an input stream. Use this function when you want to parse and process each parameter individually.
Declared In
PdiLib.h
Prototype
status_t PdiReadPropertyName (
PdiReaderType *ioReader
)
Parameters
-
→
ioReader
- The PDI reader object, which was created by a previous call to the
PdiReaderNew()
function.
Returns
Returns errNone
if successful, and an error code if not successful.
Comments
The PdiReadProperty()
function reads a property name only, reading until it encounters the PDI ":
" separator character, or until it encounters the first parameter ",
" separator character.
To then read parameters, call PdiReadParameter()
one or more times. And to read property value fields, call PdiReadPropertyField()
.
This function initializes the property
and propertyName
fields of the ioReader
object.
See Also
PdiReaderNew()
, PdiReadProperty()
PdiSetCharset Function
Purpose
Force the character set of the next property value that is written by the specified PDI writer.
Declared In
PdiLib.h
Prototype
status_t PdiSetCharset ( PdiWriterType *ioWriter
, CharEncodingTypecharset
)
Parameters
-
→
ioWriter
- The PDI writer object, which was created by a previous call to the
PdiWriterNew()
function. -
→
charset
- The character set to use for the property value. This must be a
CharEncodingType
value that is supported by the device as a valid value for thedstEncoding
parameter passed toTxtConvertEncoding()
. The valid values depend on the version and locale of the device's ROM.
Returns
Returns errNone
if successful, and an error code if not successful.
Comments
This function tells ioWriter
to use the specified charSet
for the next property value that it writes, rather than computing a character set for that value. We strongly suggest, however, not to use this function and to let the PDI library compute and set the character set.
You can determine the current character setting by examining the charset
field of your PDI writer object.
See Also
PdiSetEncoding Function
Purpose
Force the encoding of the current property value.
Declared In
PdiLib.h
Prototype
status_t PdiSetEncoding ( PdiWriterType *ioWriter
, uint16_tencoding
)
Parameters
-
→
ioReader
- The PDI writer object, which was created by a previous call to the
PdiWriterNew()
function. -
→
encoding
- The encoding to apply to the property value. This must be one of the Encoding Type Constants.
Returns
Returns errNone
if successful, and an error code if not successful.
Comments
This function changes the encoding for the property value to the specified encoding
value
You can determine the current encoding setting by examining the encoding
field of your PDI writer object.
See Also
PdiWriteBeginObject Function
Purpose
Writes a vObject begin tag to an output stream.
Declared In
PdiLib.h
Prototype
status_t PdiWriteBeginObject ( PdiWriterType *ioWriter
, uint16_tobjectNameID
)
Parameters
-
→
ioWriter
- The PDI writer object, which was created by a previous call to the
PdiWriterNew()
function. -
→
objectNameID
- The object name ID. This must be one of the Property Name Constants that begins an object, including the following:
Returns
Returns errNone
if successful, and an error code if not successful.
Comments
Call this function to begin writing a vObject to the output stream. It writes a begin tag such as "BEGIN:VCARD
" to the output stream.
See Also
PdiWriteEndObject()
, PdiWriteProperty()
PdiWriteEndObject Macro
Purpose
Writes a vObject end tag to an output stream.
Declared In
PdiLib.h
Prototype
#define PdiWriteEndObject PdiWriteBeginObject
Parameters
-
→
ioWriter
- The PDI writer object, which was created by a previous call to the
PdiWriterNew()
function. -
→
objectNameID
- The object name ID. This must be one of the Property Name Constants that ends an object, including the following:
Returns
Returns errNone
if successful, and an error code if not successful.
Comments
This macro is defined as PdiWriteBeginObject()
. The only difference is that you should pass one of the properties that ends an object in the objectNameID
parameter.
Use this macro to finish writing a vObject to the output stream. It writes an end tag such as "END:VCARD
" to the output stream.
See Also
PdiWriteBeginObject()
, PdiWriteProperty()
PdiWriteParameter Function
Purpose
Write a parameter, and optionally its name, to an output stream.
Declared In
PdiLib.h
Prototype
status_t PdiWriteParameter ( PdiWriterType *ioWriter
, uint16_tparameter
, BooleanparameterName
)
Parameters
-
→
ioWriter
- The PDI writer object, which was created by a previous call to the
PdiWriterNew()
function. -
→
parameter
- The ID of the parameter. This must be one of the Parameter Value Constants.
-
→
parameterName
- If this is
true
, the parameter name, followed by the "=
" symbol, followed by the parameter value is written to the output stream. - If this is
false
, only the parameter value is written to the output stream.
Returns
Returns errNone
if successful, and an error code if not successful.
Comments
Use this function to write a parameter to the output stream. To write a property, you usually call the PdiWriteProperty()
function, followed by calls to PdiWriteParameter()
to write any parameters, followed by a call to the PdiWritePropertyValue()
function to write the property value. For more information, see "Writing Properties."
You can use the parameterName
argument to specify that you want the parameter name written as well as the parameter value. For example, the following table shows what is written if the value of parameter
is kPdiPAV_TYPE_HOME
.
See Also
PdiWriteProperty()
, PdiWritePropertyValue()
, PdiWritePropertyFields()
, PdiWritePropertyStr()
, PdiWriteParameterStr()
PdiWriteParameterStr Function
Purpose
Write a parameter name and the parameter value to an output stream.
Declared In
PdiLib.h
Prototype
status_t PdiWriteParameterStr ( PdiWriterType *ioWriter
, const char *parameterName
, const char *parameterValue
)
Parameters
-
→
ioWriter
- The PDI writer object, which was created by a previous call to the
PdiWriterNew()
function. -
→
parameterName
- The name of the parameter. If the value of this is the empty string or
NULL
, only the parameter value is written. -
→
parameterValue
- The parameter value string.
Returns
Returns errNone
if successful, and an error code if not successful.
Comments
This function writes the parameter name, followed by the "=
" symbol, followed by the parameter value, to the output stream. If parameterName
is NULL
, or if its value is the empty string, just the parameter value is written.
This function is similar to the PdiWriteParameter()
function. The difference is that PdiWriteParameterStr()
takes the name and value of the parameter as strings, while PdiWriteParameter()
takes them as ID constants.
See Also
PdiWriteProperty()
, PdiWritePropertyValue()
, PdiWritePropertyFields()
, PdiWritePropertyStr()
, PdiWriteParameter()
PdiWriteProperty Function
Purpose
Writes a property name to an output stream.
Declared In
PdiLib.h
Prototype
status_t PdiWriteProperty ( PdiWriterType *ioWriter
, uint16_tpropertyNameID
)
Parameters
-
→
ioWriter
- The PDI writer object, which was created by a previous call to the
PdiWriterNew()
function. -
→
propertyNameID
- The property name to write. This must be one of the Property Name Constants.
Returns
Returns errNone
if successful, and an error code if not successful.
Comments
To write a property, you usually call PdiWriteProperty()
, followed by calls to the PdiWriteParameter()
function to write any parameters, followed by a call to the PdiWritePropertyValue()
function to write the property value. For more information, see "Writing Properties."
See Also
PdiWritePropertyValue()
, PdiWritePropertyFields()
, PdiWritePropertyStr()
, PdiWriteParameter()
PdiWritePropertyBinaryValue Function
Purpose
Write a binary property value to an output stream.
Declared In
PdiLib.h
Prototype
status_t PdiWritePropertyBinaryValue ( PdiWriterType *ioWriter
, const char *buffer
, uint16_tsize
, uint16_toptions
)
Parameters
-
→
ioWriter
- The PDI writer object, which was created by a previous call to the
PdiWriterNew()
function. -
→
buffer
- A buffer that contains the binary data.
-
→
size
- The number of bytes of data to write from the buffer.
-
→
options
- The data type. This must be a combination of one or more of the Value Type Constants.
Returns
Returns errNone
if successful, and an error code if not successful.
Comments
Use this function to write a binary data property value, such as a sound or an image.
This function encodes the data when it is written. The character set that gets applied to the data is not computed by this function; however, you can call the PdiSetCharset()
function to set the character set.
See Also
PdiWriteProperty()
, PdiWritePropertyFields()
, PdiWritePropertyValue()
PdiWritePropertyFields Function
Purpose
Write a structured property value with multiple fields to an output stream.
Declared In
PdiLib.h
Prototype
status_t PdiWritePropertyFields ( PdiWriterType *ioWriter
, char *fields
[], uint16_tfieldNumber
, uint16_toptions
)
Parameters
-
→
ioWriter
- The PDI writer object, which was created by a previous call to the
PdiWriterNew()
function. -
→
fields
- An array of strings, each of which is a field of the property value. Individual fields can be
NULL
. -
→
fieldNumber
- The number of fields in the
Fields
array. -
→
options
- The data type. This must be a combination of one or more of the Value Type Constants.
Returns
Returns errNone
if successful, and an error code if not successful.
Comments
Use this function to write a property value that contains multiple fields.
See Also
PdiWritePropertyValue()
, PdiWritePropertyBinaryValue()
, PdiReadPropertyField()
PdiWritePropertyStr Function
Purpose
Writes the name of a property to the output stream, and specifies the property value's structure for subsequent write operations.
Declared In
PdiLib.h
Prototype
status_t PdiWritePropertyStr ( PdiWriterType *ioWriter
, const char *propertyName
, uint8_twriteMode
, uint8_trequiredFields
)
Parameters
-
→
ioWriter
- The PDI writer object, which was created by a previous call to the
PdiWriterNew()
function. -
→
propertyName
- The name of the property to write.
-
→
writeMode
- The format of the fields in the property value. Use one of the following Property Value Format Constants:
-
→
requiredFields
- The number of required fields for the value. This is usually set to
1
.
Returns
Returns errNone
if successful, and an error code if not successful.
Comments
Use this function when you are writing a property that is not in the dictionary, or when you are writing a property that uses value formatting that differs from the standard formatting stored in the dictionary for the property name.
This function writes the property name to the output stream, and then establishes the structure of the property's value, including the number of required fields and the separator character for those fields. After calling this function, the next call to the PdiWritePropertyValue()
or PdiWritePropertyFields()
functions correctly writes the property value.
See Also
PdiWriteProperty()
, PdiWritePropertyValue()
, PdiWritePropertyFields()
, PdiWriteParameter()
PdiWritePropertyValue Function
Purpose
Write a string to the output stream as the entire value of a property.
Declared In
PdiLib.h
Prototype
status_t PdiWritePropertyValue ( PdiWriterType *ioWriter
, char *buffer
, uint16_toptions
)
Parameters
-
→
ioWriter
- The PDI writer object, which was created by a previous call to the
PdiWriterNew()
function. -
→
buffer
- The input buffer that contains the string to be written.
-
→
options
- The data type. This must be a combination of one or more of the Value Type Constants.
Returns
Returns errNone
if successful, and an error code if not successful.
See Also
PdiWriteProperty()
, PdiWritePropertyFields()
, PdiWriteParameter()
, PdiWritePropertyBinaryValue()
PdiWriterDelete Function
Purpose
Delete a PDI output stream object.
Declared In
PdiLib.h
Prototype
void PdiWriterDelete (
PdiWriterType **ioWriter
)
Parameters
-
↔
ioWriter
- A pointer to the PDI writer object, which was created by a previous call to the
PdiWriterNew()
function.
Returns
Comments
This function frees the memory that was allocated for the writer object. The ioWriter
parameter is set to NULL
.
See Also
PdiWriterNew Function
Purpose
Initializes a new PDI writer object for use with the specified library number.
Declared In
PdiLib.h
Prototype
PdiWriterType *PdiWriterNew ( UDAWriterType *output
, uint16_tversion
)
Parameters
-
→
output
- The Unified Data Access (UDA) output object associated with the writer.
-
→
version
- Options to control the behavior of the writer. You can use a combination of the Reader and Writer Options Constants.
Returns
Returns a pointer to the new PDI writer object. Returns NULL
if the reader cannot be created.
Comments
The media
pointer is copied into a field in the writer object; thus, you do not need to retain your copy.
See Also
PdiWriterDelete()
, PdiReaderNew()