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

88    Personal Data Interchange Library

Palm OS® Programmer's API Reference

Palm OS® 68K SDK

     

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 3, "Personal Data Interchange," in Palm OS Programmer's Companion, vol. II, Communications.

PDI Library Data Structures ^TOP^

This section describes the data structures used with the PDI library functions.

PdiDictionary Typedef ^TOP^

Purpose

The PdiDictionary type is a simple typedef that represents an internal, binary object.

Prototype

typedef UInt8 PdiDictionary;

PdiReaderType Struct ^TOP^

Purpose

The PdiReaderType data structure represents a PDI reader object, which you use to read data from an input stream.

Prototype

typedef struct _PdiReader {
Er error;
UInt8 encoding;
CharEncodingType charset;
UInt16 written;
UInt8 fieldNum;
UInt16 property;
UInt16 propertyValueType;
UInt16 parameter;
UInt32 parameterPairs[kPDI_ENTRIES_NUMBER];
UInt16 customFieldNumber;
void *appData;
UInt16 pdiRefNum;
UInt16 events;
Char *groupName;
Char *propertyName;
Char *parameterName;
Char *parameterValue;
Char *propertyValue;
PdiDictionary *dictionary[2];
} PdiReaderType

Fields

error
The most recent error.
encoding
The type of encoding for the property value.
charset
The character set of the property value.
written
The number of characters that have currently been written to the buffer.
fieldNum
The current field number.
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.
parameterPairs
An integer array with bits set for each parameter value that has been parsed for the current property value.
You must use the PdiParameterPairTest macro to access this field.
customFieldNumber
The number of the custom field parsed by the reader for the current property. Custom fields are used in the Palm Address Book.
appData
Application-dependent data field.
pdiRefNum
The library reference number associated with this reader.
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.

dictionary

An array of two dictionary pointers. The dictionary[0] entry is the main dictionary built into the PDI library, and the dictionary[1] entry is an optional, custom dictionary associated with the reader object with a call to PdiDefineReaderDictionary().

PdiWriterType Struct ^TOP^

Purpose

The PdiWriterType data structure represents a PDI writer object, which you use to write data to an output stream.

Prototype

typedef struct _PdiWriter {
void *appData;
UInt16 pdiRefNum;
UInt16 encoding;
CharEncodingType charset;
Err error;
PdiDictionary *dictionary[2];
} PdiWriterType

Fields

appData
Application-dependent data field.
pdiRefNum
The library reference number associated with this reader.
encoding
The type of encoding for the property value.
charset
The character set of the property value.
error
The most recent error.
dictionary
An array of two dictionary pointers. The dictionary[0] entry is the main dictionary built into the PDI library, and the dictionary[1] entry is an optional, custom dictionary associated with the reader object with a call to PdiDefineReaderDictionary().

PDI Library Constants ^TOP^

This section describes the constants used in the PDI library, which include the following constant types:

Buffer Management Constants ^TOP^

You use the buffer management constants to determine how buffers are managed in the PDI reader.

Constant

Value

Description

kPdiResizableBuffer

0xFFFF

Indicates that the buffer can be automatically resized by the PDI library.

kPdiDefaultBufferMaxSize

0x3FFF

The default maximum buffer size, in bytes. You can change the maximum size of a reader's buffer by calling the PdiDefineResizing() function.

kPdiDefaultBufferDeltaSize

0x0010

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 PdiDefineResizing() function.

Encoding Type Constants ^TOP^

You use the encoding type constants to specify the type of encoding used in a vObject reader or writer.

Constant

Value

Description

kPdiASCIIEncoding

0

The vObject is not encoded.

kPdiQPEncoding

kPdiPAV_ENCODING_
QUOTED_PRINTABLE

The vObject uses the quoted printable encoding.

kPdiB64Encoding

kPdiPAV_ENCODING_
BASE64

The vObject uses Base 64 encoding. The writer outputs "ENCODING=BASE64."

kPdiBEncoding

kPdiPAV_ENCODING_B

The vObject uses Base 64 encoding. This is the same as the kPdiB64Encoding value, except that the PDI writer outputs "ENCODING=B."

This encoding is used with the vCard 3.0 standard.

kPdiEscapeEncoding

0x8000

The vObject uses escapes for special characters.

kPdiNoEncoding

0x8001

The PDI writer does not encode the vObject value.

Error Code Constants ^TOP^

The PDI library functions return the error code constants shown in the following table to indicate their status.

Constant

Description

pdiErrRead

An error occurred while reading from the input stream.

pdiErrWrite

An error occurred while writing to the output stream.

pdiErrNoPropertyName

An attempt was made to write a property value before the property name was written.

pdiErrNoPropertyValue

The application did not write the last property value.

pdiErrMoreChars

The buffer is full. Superfluous characters have been discarded.

pdiErrNoMoreFields

There are no more property fields to read.

pdiErrOpenFailed

The PDI library could not be opened.

pdiErrCloseFailed

The PDI library could not be closed. This can occur if another application is using the library.

Parameter Name Constants ^TOP^

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 parameterValue is replaced by a parameter name.

The following table shows examples of parameter name constants. For a complete list, see the PdiConst.h file.

Constant

Description

kPdiPAN_TYPE

The TYPE parameter.

kPdiPAN_ENCODING

The ENCODING parameter.

kPdiPAN_STATUS

The STATUS parameter.

Parameter Value Constants ^TOP^

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.

Constant

Description

kPdiPAV_TYPE_TEL

The parameter name is TYPE and the parameter value is TEL.

kPdiPAV_ENCODING_BASE64

The parameter name is ENCODING and parameter value is BASE64.

kPdiPAV_ENCODING_8BIT

The parameter name is ENCODING and the parameter value is 8BIT.

kPdiPAV_STATUS_ACCEPTED

The parameter name is STATUS and the parameter value is ACCEPTED.

Property Name Constants ^TOP^

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.

Constant

Description

kPdiPRN_ADR

The ADR property.

kPdiPRN_BDAY

The BDAY property.

kPdiPRN_BEGIN

The BEGIN property.

kPdiPRN_BEGIN_VCARD

The BEGIN:VCARD property.

Property Type Constants ^TOP^

You use the property type constants to specify the data type of a property.

Constant

Value

Description

kPdiType_URI

0

The data is a uniform resource identifier.

kPdiType_UTC_OFFSET

1

The data is an offset from UTC to local time.

kPdiType_RECUR

2

The data is a specification of a recurrence rule.

kPdiType_PERIOD

3

The data is a precise period of time.

kPdiType_CAL_ADDRESS

4

Calendar user data.

kPdiType_BINARY

5

Binary data.

kPdiType_TEXT

6

Text data.

kPdiType_FLOAT

7

Floating-point data.

kPdiType_DURATION

8

Time duration data.

kPdiType_DATE_TIME

9

Calendar date and time data.

kPdiType_DATE

10

Date data.

kPdiType_INTEGER

11

Signed integer data.

kPdiType_TIME

12

Time-of-day data.

Property Value Field Constants ^TOP^

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.

Constant

Description

kPdiPVF_ADR_POST_OFFICE

The property value field that stores the post office portion of the address.

kPdiPVF_ADR_EXTENDED

The property value field that stores the extended portion of the address.

kPdiPAN_ADR_COUNTRY

The property value field that stores the country portion of the address.

Property Value Format Constants ^TOP^

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.

Constant

Value

Description

kPdiNoFields

0

There are no fields in the property value; PdiReadPropertyField() reads the entire value, or PdiWritePropertyStr() specifies that the entire value should be written.

kPdiCommaFields

1

Fields are separated with comma (",") characters; PdiReadPropertyField() reads one field, or PdiWritePropertyStr() specifies that one field should be written.

kPdiSemicolonFields

2

Fields are separated with semicolon (";") characters; PdiReadPropertyField() reads one field, or PdiWritePropertyStr() specifies that one field should be written.

kPdiDefaultFields

4

The parser decides the property value format, based on the property name.

kPdiConvertComma

8

Fields are separated with comma characters; PdiReadPropertyField() reads the entire value and converts each comma into a newline ("\n") character.

kPdiConvertSemicolon

16

Fields are separated with semicolon characters; PdiReadPropertyField() reads the entire value and converts each semicolon into a newline ("\n") character.

Reader and Writer Options Constants ^TOP^

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.

Constant

Value

Description

kPdiEnableFolding

1

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 earlier versions of the Palm OS®.

Also note that other encoding formats, including quoted-printable and Base 64, define their own mechanisms for splitting long lines.

kPdiEnableQuotedPrintable

2

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 earlier versions of the Palm OS.

If you do not specify this option, the default encoding is Base 64.

kPdiEscapeMultiFieldValues

4

For compatibility with earlier versions of the Palm OS.

You must enable this for compatibility with earlier versions of the Palm OS. 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 in the Palm OS Programmer's Companion, vol. II, Communications.

kPdiPalmCompatibility

6

This is a combination of kPdiEnableQuotedPrintable | kPdiEscapeMultiFieldValues.

It forces the PDI writer to generate output that is compatible with earlier versions of the Palm OS.

kPdiEnableB

8

Enables base 64 encoding in the output stream, and tells the PDI writer to output "ENCODING=B" instead of "ENCODING=BASE64" when encoding a value with Base 64.

Note: the vCard 3.0 standard has replaced the earlier ENCODING=BASE64 with ENCODING=B. The meaning is the same.

kPdiOpenParser

8

Specifies that the PDI reader is open to all formats, including Palm and others.

Reader Event Constants ^TOP^

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.

Constant

Value

Description

kPdiEOFEventMask

1

End of file was reached.

kPdiGroupNameEventMask

2

A group name was found.

kPdiPropertyNameEventMask

4

A property name was found.

kPdiParameterNameEventMask

8

A parameter name was found.

kPdiParameterValueEventMask

16

A parameter value was found.

kPdiPropertyDefinedEventMask

32

A property definition was found; this implies that the ":" separator character was found.

kPdiPropertyValueEventMask

64

An entire property value was found

kPdiPropertyValueFieldEventMask

128

A value field was found; this implies that the ";" separator character was found.

kPdiPropertyValueItemEventMask

256

A value item was found; this implies that the "," separator character was found.

kPdiPropertyValueMoreCharsEventMask

512

The buffer that you provided was not large enough. The superfluous characters have been discarded.

kPdiBeginObjectEventMask

1024

The object begin indicator BEGIN was reached.

kPdiEndObjectEventMask

2048

The object end indicator END was reached.

Value Type Constants ^TOP^

You can use the following constants to specify data typing information for the PdiWritePropertyBinaryValue(), PdiWritePropertyFields(), and PdiWritePropertyValue() functions.

Constant

Value

Description

kPdiWriteData

0

The value is data. The PDI writer does not compute a character set. You can use this for binary data or pure ASCII data.

kPdiWriteText

8

The value is text data. The PDI writer parses the data character by character to compute the correct charset and character encoding for the data.

kPdiWriteMultiline

16

Explicitly specifies that the value contains special characters, such as newlines, and must be encoded. If this flag is not specified, the encoding is determined by the applied character set.

PDI Library Functions ^TOP^

PdiDefineReaderDictionary Function ^TOP^

Purpose

Installs a new custom dictionary for use with a PDI reader object.

Declared In

PdiLib.h

Prototype

PdiDictionary *PdiDefineReaderDictionary (
   UInt16libRefnum,
   PdiReaderType *ioReader,
   PdiDictionary*dictionary,
   BooleandisableMainDictionary
)

Parameters

libRefnum
The PDI library reference number.
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; if false, 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,

Note that the dictionary must have previously been compiled by the dictionary tool. For more information, review the PDI sample code, which you can find on the Palm Developer's Knowledge Base at http://www.palmos.com/dev/tech/kb.

PdiDefineResizing Function ^TOP^

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

Err PdiDefineResizing(
   UInt16libRefnum,
   PdiReaderType*ioReader,
   UInt16deltaSize,
   UInt16maxSize
)

Parameters

libRefnum
The PDI library reference number.
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:

kPdiDefaultBufferDeltaSize0x0010
kPdiDefaultBufferMaxSize0x3FFF

Compatibility

Implemented only if 4.0 New Feature Set is present.

PdiDefineWriterDictionary Function ^TOP^

Purpose

Installs a new custom dictionary for use with a PDI writer object.

Declared In

PdiLib.h

Prototype

PdiDictionary *PdiDefineWriterDictionary (
   UInt16libRefnum,
   PdiWriterType *ioWriter,
   PdiDictionary*dictionary,
   BooleandisableMainDictionary
)

Parameters

libRefnum
The PDI library reference number.
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; if false, 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,

Note that the dictionary must have previously been compiled by the dictionary tool. For more information, review the PDI sample code, which you can find on the Palm Developer's Knowledge Base at http://www.palmos.com/dev/tech/kb/.

PdiEnterObject Function ^TOP^

Purpose

Tells the PDI library to enter into a recursively-defined object.

Declared In

PdiLib.h

Prototype

Err PdiEnterObject(
   UInt16libRefnum,
   PdiReaderType*ioReader
)

Parameters

libRefnum
The PDI library reference number.
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.

Compatibility

Implemented only if 4.0 New Feature Set is present.

PdiLibClose Function ^TOP^

Purpose

Close the PDI library after your application has finished with it.

Declared In

PdiLib.h

Prototype

Err PdiLibClose(
   UInt16libRefnum
)

Parameters

libRefnum
The PDI library reference number.

Returns

Returns 0 if no other application uses the library. You may need to call SysLibRemove() to remove the PDI library from the system library table.

Returns pdiErrCloseFailed if the library could not be closed.

Comments

You should call this function after your application has finished with the PDI library, to allow the resources to be recovered.

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

PdiLibOpen()

PdiLibOpen Function ^TOP^

Purpose

Opens the PDI library for use by your application.

Declared In

PdiLib.h

Prototype

Err PdiLibOpen(
   UInt16libRefnum
)

Parameters

libRefnum
The PDI library reference number.

Returns

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

Comments

You must call this function before calling any of the other PDI functions.

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

PdiLibClose()

PdiParameterPairTest Macro ^TOP^

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:

Name=Value
Value

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:

Type=WORK
WORK

Compatibility

Implemented only if 4.0 New Feature Set is present.

PdiReaderDelete Function ^TOP^

Purpose

Delete a PDI reader object that is associated with the specified library number.

Declared In

PdiLib.h

Prototype

void PdiReaderDelete(
   UInt16libRefnum,
   PdiReaderType**ioReader
)

Parameters

libRefnum
The PDI library reference number.
ioReader
A pointer to the PDI reader object, which was created by a previous call to the PdiReaderNew() function.

Returns

Returns nothing.

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.

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

PdiReaderNew()

PdiReaderNew Function ^TOP^

Purpose

Create and initialize a new PDI reader object for use with the specified PDI library number.

Declared In

PdiLib.h

Prototype

PdiReaderType *PdiReaderNew(
   UInt16libRefnum,
   UDAReaderType*input,
   UInt16version
)

Parameters

libRefnum
The PDI library reference number.
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 89, "Unified Data Access Manager."

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

PdiReaderDelete(), PdiWriterNew()

PdiReadParameter Function ^TOP^

Purpose

Read a single parameter name and its value from an input stream.

Declared In

PdiLib.h

Prototype

Err PdiReadParameter(
   UInt16libRefnum,
   PdiReaderType*ioReader
)

Parameters

libRefnum
The PDI library reference number.
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.

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.

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

PdiReaderNew(), PdiReadPropertyField(), PdiReadPropertyName()

PdiReadProperty Function ^TOP^

Purpose

Read the next property and its parameters from the input stream.

Declared In

PdiLib.h

Prototype

Err PdiReadProperty(
   UInt16libRefnum,
   PdiReaderType*ioReader
)

Parameters

libRefnum
The PDI library reference number.
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 in Chapter 3, "Personal Data Interchange," in Palm OS Programmer's Companion, vol. II, Communications.

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 in Chapter 3, "Personal Data Interchange," in Palm OS Programmer's Companion, vol. II, Communications.

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

PdiReaderNew(), PdiReadPropertyField(), PdiReadPropertyName(), PdiReadParameter()

PdiReadPropertyField Function ^TOP^

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

Err PdiReadPropertyField(
   UInt16libRefnum,
   PdiReaderType*ioReader,
   Char**bufferPP,
   UInt16bufferSize,
   UInt16readMode
)

Parameters

libRefnum
The PDI library reference number.
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 that buffer 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 in Chapter 3, "Personal Data Interchange," in Palm OS Programmer's Companion, vol. II, Communications.

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

PdiReaderNew(), PdiReadProperty(), PdiReadPropertyName(), PdiReadParameter()

PdiReadPropertyName Function ^TOP^

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

Err PdiReadPropertyName(
   UInt16libRefnum,
   PdiReaderType*ioReader
)

Parameters

libRefnum
The PDI library reference number.
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.

This function initializes the property and propertyName fields of the ioReader object.

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

PdiReaderNew(), PdiReadPropertyField(), PdiReadProperty(), PdiReadParameter()

PdiSetCharset Function ^TOP^

Purpose

Force the character set of the next property value that is written by the specified PDI writer.

Declared In

PdiLib.h

Prototype

Err PdiSetCharset(
   UInt16libRefnum,
   PdiWriterType*ioWriter,
   CharEncodingTypecharset
)

Parameters

libRefnum
The PDI library reference number.
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 one of the following CharEncodingType values:
charEncodingAscii
charEncodingISO8859_1
charEncodingShiftJIS
charEncodingISO2022Jp

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.

You can determine the current character setting by examining the charset field of your PDI writer object.

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

PdiSetEncoding()

PdiSetEncoding Function ^TOP^

Purpose

Force the encoding of the current property value.

Declared In

PdiLib.h

Prototype

Err PdiSetEncoding(
   UInt16libRefnum,
   PdiWriterType*ioWriter,
   UInt16encoding
)

Parameters

libRefnum
The PDI library reference number.
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.

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

PdiSetCharset()

PdiWriteBeginObject Function ^TOP^

Purpose

Writes a vObject begin tag to an output stream.

Declared In

PdiLib.h

Prototype

Err PdiWriteBeginObject(
   UInt16libRefnum,
   PdiWriterType*ioWriter,
   UInt16objectNameID
)

Parameters

libRefnum
The PDI library reference number.
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:
kPdiPRN_BEGIN_VCAL
kPdiPRN_BEGIN_VCAL
kPdiPRN_BEGIN_VCARD
kPdiPRN_BEGIN_VEVENT
kPdiPRN_BEGIN_VFREEBUSY
kPdiPRN_BEGIN_VJOURNAL
kPdiPRN_BEGIN_VTIMEZONE
kPdiPRN_BEGIN_VTODO

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.

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

PdiWriteEndObject(), PdiWriteProperty()

PdiWriteEndObject Function ^TOP^

Purpose

Writes a vObject end tag to an output stream.

Declared In

PdiLib.h

Prototype

Err PdiWriteEndObject(
   UInt16libRefnum,
   PdiWriterType*ioWriter,
   UInt16objectNameID
)

Parameters

libRefnum
The PDI library reference number.
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:
kPdiPRN_END_VCAL
kPdiPRN_END_VCAL
kPdiPRN_END_VCARD
kPdiPRN_END_VEVENT
kPdiPRN_END_VFREEBUSY
kPdiPRN_END_VJOURNAL
kPdiPRN_END_VTIMEZONE
kPdiPRN_END_VTODO

Returns

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

Comments

Call this function to finish writing a vObject to the output stream. It writes a end tag such as "END:VCARD" to the output stream.

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

PdiWriteBeginObject(), PdiWriteProperty()

PdiWriteParameter Function ^TOP^

Purpose

Write a parameter, and optionally its name, to an output stream.

Declared In

PdiLib.h

Prototype

Err PdiWriteParameter(
   UInt16libRefnum,
   PdiWriterType*ioWriter,
   UInt16parameter,
   BooleanparameterName
)

Parameters

libRefnum
The PDI library reference number.
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 in Chapter 3, "Personal Data Interchange," in Palm OS Programmer's Companion, vol. II, Communications.

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.

Value of parameterName

Data written to output stream

true

TYPE=HOME

false

HOME

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

PdiWriteProperty(), PdiWritePropertyValue(), PdiWritePropertyFields(), PdiWritePropertyStr(), PdiWriteParameterStr()

PdiWriteParameterStr Function ^TOP^

Purpose

Write a parameter name and the parameter value to an output stream.

Declared In

PdiLib.h

Prototype

Err PdiWriteParameterStr(
   UInt16libRefnum,
   PdiWriterType*ioWriter,
   constChar*parameterName,
   constChar*parameterValue
)

Parameters

libRefnum
The PDI library reference number.
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.

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

PdiWriteProperty(), PdiWritePropertyValue(), PdiWritePropertyFields(), PdiWritePropertyStr(), PdiWriteParameter()

PdiWriteProperty Function ^TOP^

Purpose

Writes a property name to an output stream.

Declared In

PdiLib.h

Prototype

Err PdiWriteProperty(
   UInt16libRefnum,
   PdiWriterType*ioWriter,
   UInt16propertyNameID
)

Parameters

libRefnum
The PDI library reference number.
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 in Chapter 3, "Personal Data Interchange," in Palm OS Programmer's Companion, vol. II, Communications.

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

PdiWritePropertyValue(), PdiWritePropertyFields(), PdiWritePropertyStr(), PdiWriteParameter()

PdiWritePropertyBinaryValue Function ^TOP^

Purpose

Write a binary property value to an output stream.

Declared In

PdiLib.h

Prototype

Err PdiWritePropertyBinaryValue(
   UInt16libRefnum,
   PdiWriterType*ioWriter,
   constChar*buffer,
   UInt16size,
   UInt16options
)

Parameters

libRefnum
The PDI library reference number.
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.

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

PdiWriteProperty(), PdiWritePropertyFields(), PdiWritePropertyValue()

PdiWritePropertyFields Function ^TOP^

Purpose

Write a structured property value with multiple fields to an output stream.

Declared In

PdiLib.h

Prototype

Err PdiWritePropertyFields(
   UInt16libRefnum,
   PdiWriterType*ioWriter,
   Char*fields[],
   UInt16fieldNumber,
   UInt16options
)

Parameters

libRefnum
The PDI library reference number.
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.

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

PdiWritePropertyValue(), PdiWritePropertyBinaryValue(), PdiReadPropertyField()

PdiWritePropertyStr Function ^TOP^

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

Err PdiWritePropertyStr(
   UInt16libRefnum,
   PdiWriterType*ioWriter,
   constChar*propertyName,
   UInt8writeMode,
   UInt8requiredFields
)

Parameters

libRefnum
The PDI library reference number.
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:
kPdiNoFields
kPdiCommaFields
kPdiSemicolonFields
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.

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

PdiWriteProperty(), PdiWritePropertyValue(), PdiWritePropertyFields(), PdiWriteParameter()

PdiWritePropertyValue Function ^TOP^

Purpose

Write a string to the output stream as the entire value of a property.

Declared In

PdiLib.h

Prototype

Err PdiWritePropertyValue(
   UInt16libRefnum,
   PdiWriterType*ioWriter,
   Char*buffer,
   UInt16options
)

Parameters

libRefnum
The PDI library reference number.
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.

Comments

Use this function to write a property value that contains a single field.

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

PdiWriteProperty(), PdiWritePropertyFields(), PdiWriteParameter(), PdiWritePropertyBinaryValue()

PdiWriterDelete Function ^TOP^

Purpose

Delete a PDI output stream object.

Declared In

PdiLib.h

Prototype

void PdiWriterDelete(
   UInt16libRefnum,
   PdiWriterType**ioWriter
)

Parameters

libRefnum
The PDI library reference number.
ioWriter
A pointer to the PDI writer object, which was created by a previous call to the PdiWriterNew() function.

Returns

Returns nothing.

Comments

This function frees the memory that was allocated for the writer object. The ioWriter parameter is set to NULL.

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

PdiWriterNew()

PdiWriterNew Function ^TOP^

Purpose

Initializes a new PDI writer object for use with the specified library number.

Declared In

PdiLib.h

Prototype

PdiWriterType *PdiWriterNew(
   UInt16libRefnum,
   UDAWriterType*output,
   UInt16version
)

Parameters

libRefnum
The PDI library reference number.
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.

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

PdiWriterDelete(), PdiReaderNew()