Classes
struct	MA_PIM_ARGS
	Arguments for PIM functions. More...
Typedefs
typedef struct MA_PIM_ARGS	MA_PIM_ARGS
	Arguments for PIM functions.
Functions
MAHandle	maPimListOpen (int listType)
	Opens a PimList. Use maPimListNext() to open the list's items.
MAHandle	maPimListNext (MAHandle list)
	Returns a handle to the next PimItem in the list, or 0 if there are no more items, or < 0 on error. You must use maPimItemClose() on every item to prevent memory leaks.
int	maPimListClose (MAHandle list)
	Closes a PimList.
int	maPimItemCount (MAHandle item)
	Returns the number of fields in the item.
int	maPimItemGetField (MAHandle item, int n)
	Returns the field id of the item's n:th field. Panics on invalid indices.
int	maPimItemFieldCount (MAHandle item, int field)
	Returns the number of values in the field for a given item.
int	maPimItemGetAttributes (MAHandle item, int field, int index)
	Returns the attribute for the specified value in a field and item. Panics on field/index combinations that don't exist in this item.
int	maPimItemSetLabel (const MA_PIM_ARGS *args, int index)
	Sets a custom label for a value in a field and item. Panics on field/index combinations that don't exist in this item. The value's attribute must be set to custom. The label has MA_PIM_TYPE_STRING and is stored in args.buf. args.bufSize must be valid.
int	maPimItemGetLabel (const MA_PIM_ARGS *args, int index)
int	maPimFieldType (MAHandle list, int field)
int	maPimItemGetValue (const MA_PIM_ARGS *args, int index)
int	maPimItemSetValue (const MA_PIM_ARGS *args, int index, int attributes)
int	maPimItemAddValue (const MA_PIM_ARGS *args, int attributes)
int	maPimItemRemoveValue (MAHandle item, int field, int index)
int	maPimItemClose (MAHandle item)
MAHandle	maPimItemCreate (MAHandle list)
int	maPimItemRemove (MAHandle list, MAHandle item)

Typedef Documentation

typedef struct MA_PIM_ARGS MA_PIM_ARGS

Arguments for PIM functions.

Function Documentation

MAHandle maPimListOpen ( int listType )

Opens a PimList. Use maPimListNext() to open the list's items.

Parameters:

listType One of the MA_PIM constants.

Returns:: >= 0 A PimList handle. < 0 on error: MA_PIM_ERR_LIST_ALREADY_OPENED if the list is already opened. MA_PIM_ERR_LIST_UNAVAILABLE if the list is not available on the current platform. MA_PIM_ERR_LIST_TYPE_INVALID if the given list type is invalid.

References maIOCtl().

MAHandle maPimListNext ( MAHandle list )

Returns a handle to the next PimItem in the list, or 0 if there are no more items, or < 0 on error. You must use maPimItemClose() on every item to prevent memory leaks.

Parameters:

list	List handle provided by maPimListOpen(int listType).

Returns:: > 0 a PimItem handle. \= 0 if there are no more items. < 0 on error: MA_PIM_ERR_HANDLE_INVALID if the list handle is invalid.

References maIOCtl().

int maPimListClose ( MAHandle list )

Closes a PimList.

Parameters:

list	List handle provided by maPimListOpen(int listType).

Returns:: MA_PIM_ERR_NONE on success, or < 0 on error. #MA_PIM_ERR_LIST_NOT_OPENED if the list is not opened. #MA_PIM_ERR_UNAVAILABLE_LIST if the list is unavailable. #MA_PIM_ERR_INVALID_HANDLE if the list handle is invalid.

Note:: This does not close the list's items, but it does invalidate them, so that maPimItemClose() is the only function you can safely use on them.

References maIOCtl().

int maPimItemCount ( MAHandle item )

Returns the number of fields in the item.

Parameters:

item	Item handle provided by maPimListNext(MAHandle list).

Returns:: >= 0 the number of fields in the item. < 0 on error: MA_PIM_ERR_HANDLE_INVALID if the item handle is invalid.

References maIOCtl().

int maPimItemGetField	(	MAHandle	item,
		int	n
	)

Returns the field id of the item's n:th field. Panics on invalid indices.

Parameters:

item	Opened by maPimListNext().
n	>= 0 and < maPimItemCount().

Returns:: > 0 one of the MA_PIM_FIELD constants. < 0 on error: MA_PIM_ERR_HANDLE_INVALID if the item handle is invalid. MA_PIM_ERR_INDEX_INVALID if the param n is not valid.

Note:: On Android and iOS the panic system can be disabled so you'll get error codes instead.

References maIOCtl().

int maPimItemFieldCount	(	MAHandle	item,
		int	field
	)

Returns the number of values in the field for a given item.

Parameters:

item	Opened by maPimListNext().
field	One of the MA_PIM_FIELD constants.

Returns:: > 0 the number of values in the field. \= 0 if the item field has no values. < 0 on error: MA_PIM_ERR_HANDLE_INVALID if the item handle is invalid. MA_PIM_ERR_FIELD_UNSUPPORTED if the field is unsupported. MA_PIM_ERR_FIELD_INVALID if the field is invalid.

References maIOCtl().

int maPimItemGetAttributes	(	MAHandle	item,
		int	field,
		int	index
	)

Returns the attribute for the specified value in a field and item. Panics on field/index combinations that don't exist in this item.

Parameters:

item	Opened by maPimListNext().
field	One of the MA_PIM_FIELD constants.
index	>= 0 and < maPimItemFieldCount().

Returns:: > 0 the attribute for the specified field. \= 0 if the field doesn't have attributes. < 0 on error: MA_PIM_ERR_HANDLE_INVALID if the item handle is invalid. MA_PIM_ERR_FIELD_INVALID if the field is invalid. MA_PIM_ERR_FIELD_UNSUPPORTED if the field type is unsupported. MA_PIM_ERR_FIELD_EMPTY if the given field doesn't have values. MA_PIM_ERR_INDEX_INVALID if the index is invalid.

Note:: On Android and iOS the panic system can be disabled so you'll get error codes instead.

References maIOCtl().

int maPimItemSetLabel	(	const MA_PIM_ARGS *	args,
		int	index
	)

Sets a custom label for a value in a field and item. Panics on field/index combinations that don't exist in this item. The value's attribute must be set to custom. The label has MA_PIM_TYPE_STRING and is stored in args.buf. args.bufSize must be valid.

Parameters:

args	Common arguments.
index	An index into the field's value array. This is a number >= 0 and < the return value of maPimItemFieldCount().

Returns:: MA_PIM_ERR_NONE on success. MA_PIM_ERR_HANDLE_INVALID if the item handle is invalid. MA_PIM_ERR_FIELD_INVALID if the field is invalid. MA_PIM_ERR_FIELD_UNSUPPORTED if the field type is unsupported. MA_PIM_ERR_FIELD_EMPTY if the given field doesn't have values. MA_PIM_ERR_FIELD_READ_ONLY if the field is read-only. MA_PIM_ERR_INDEX_INVALID if the index is invalid. MA_PIM_ERR_NO_LABEL if the attribute is not set to custom.

Note:: This function is available only on Android or iOS.; On Android and iOS the panic system can be disabled so you'll get error codes instead.

References maIOCtl().

int maPimItemGetLabel	(	const MA_PIM_ARGS *	args,
		int	index
	)

Retrieves the custom label for a value in a field and item, if the value has a custom label. The label has MA_PIM_TYPE_STRING and is stored in args.buf. args.bufSize must be valid.

Parameters:

args	Common arguments.
index	An index into the field's value array. This is a number >= 0 and < the return value of maPimItemFieldCount().

Returns:: >= 0 the number of bytes occupied by the value. < 0 on error: MA_PIM_ERR_HANDLE_INVALID if the item handle is invalid. MA_PIM_ERR_FIELD_INVALID if the field is invalid. MA_PIM_ERR_FIELD_UNSUPPORTED if the field type is unsupported. MA_PIM_ERR_FIELD_EMPTY if the given field doesn't have values. MA_PIM_ERR_INDEX_INVALID if the index is invalid. MA_PIM_ERR_NO_LABEL if the attribute type is not set to custom. #MA_PIM_ERR_BUFFER_TOO_SMALL if the size of the value is greaten than bufSize.

Note:: This function is available on Android or iOS.

References maIOCtl().

int maPimFieldType	(	MAHandle	list,
		int	field
	)

Returns one of the type of the field.

Parameters:

list	Opened by maPimListOpen().
field	One of the MA_PIM_FIELD constants.

Returns:: >= 0 any of the MA_PIM_TYPE constants. < 0 on error: MA_PIM_ERR_HANDLE_INVALID if the list handle is invalid. MA_PIM_ERR_FIELD_INVALID if the field is invalid. MA_PIM_ERR_FIELD_UNSUPPORTED if the field type is unsupported.

References maIOCtl().

int maPimItemGetValue	(	const MA_PIM_ARGS *	args,
		int	index
	)

Copies the specified value from a field and item to args.buf.

Parameters:

args	Common arguments.
index	An index into the field's value array. This is a number >= 0 and < the return value of maPimItemFieldCount().

Returns:: >= 0 The number of bytes occupied by the value. < 0 on error: MA_PIM_ERR_HANDLE_INVALID if the item handle is invalid. MA_PIM_ERR_FIELD_INVALID if the field is invalid. MA_PIM_ERR_FIELD_UNSUPPORTED if the field type is unsupported. MA_PIM_ERR_FIELD_EMPTY if the given field doesn't have values. MA_PIM_ERR_INDEX_INVALID if the index is invalid. MA_PIM_ERR_FIELD_WRITE_ONLY if the field is write-only.

References maIOCtl().

int maPimItemSetValue	(	const MA_PIM_ARGS *	args,
		int	index,
		int	attributes
	)

Changes a value and its attributes in a field and item. This function cannot be used to add a new value.

Parameters:

args	Common arguments.
index	An index into the field's value array. This is a number >= 0 and < the return value of maPimItemFieldCount().
attributes	The value's new attributes.

Returns:: MA_PIM_ERR_NONE on success. MA_PIM_ERR_HANDLE_INVALID if the item handle is invalid. MA_PIM_ERR_FIELD_INVALID if the field is invalid. MA_PIM_ERR_FIELD_UNSUPPORTED if the field type is unsupported. MA_PIM_ERR_FIELD_READ_ONLY if the field is read-only. MA_PIM_ERR_FIELD_EMPTY if the given field doesn't have values. MA_PIM_ERR_INDEX_INVALID if the index is invalid. MA_PIM_ERR_ATTRIBUTE_COMBO_UNSUPPORTED if the field/attribute combination is not supported. MA_PIM_ERR_BUFFER_INVALID if the buffer is not valid.

Note:: The new value is not actually written to disk until the item is closed with maPimItemClose(). If the program exits before then, the changes are lost.; When setting a value with MA_PIM_TYPE_STRING_ARRAY, at least one string must be present and have a length greater than zero. Any surplus strings are ignored.

References maIOCtl().

int maPimItemAddValue	(	const MA_PIM_ARGS *	args,
		int	attributes
	)

Adds a new value to a field and item.

Parameters:

args	Common arguments.
attributes	The new value's attributes.

Returns:: />= 0 the index of the new added value. /< 0 on error: MA_PIM_ERR_HANDLE_INVALID if the item handle is invalid. MA_PIM_ERR_FIELD_INVALID if the field is invalid. MA_PIM_ERR_FIELD_UNSUPPORTED if the field type is unsupported. MA_PIM_ERR_FIELD_READ_ONLY if the field is read-only. MA_PIM_ERR_FIELD_COUNT_MAX if more values cannot be added to this field. MA_PIM_ERR_ATTRIBUTE_COMBO_UNSUPPORTED if the field/attribute combination is not supported. MA_PIM_ERR_BUFFER_INVALID if the buffer is not valid.

Note:: The new value is not actually written to disk until the item is closed with maPimItemClose(). If the program exits before then, the changes are lost.

References maIOCtl().

int maPimItemRemoveValue	(	MAHandle	item,
		int	field,
		int	index
	)

Removes a value from a field and item.

Parameters:

item	Opened by maPimListNext().
field	One of the MA_PIM_FIELD constants.
index	>= 0 and < maPimItemFieldCount().

Returns:: MA_PIM_ERR_NONE on success. MA_PIM_ERR_HANDLE_INVALID if the item handle is invalid. MA_PIM_ERR_FIELD_INVALID if the field is invalid. MA_PIM_ERR_FIELD_UNSUPPORTED if the field type is unsupported. MA_PIM_ERR_FIELD_READ_ONLY if the field is read-only. MA_PIM_ERR_FIELD_EMPTY if the given field doesn't have values. MA_PIM_ERR_INDEX_INVALID if the index is invalid.

Note:: The changes is not actually written to disk until the item is closed with maPimItemClose(). If the program exits before then, the changes are lost.

References maIOCtl().

int maPimItemClose ( MAHandle item )

Closes the handle to a PimItem, releasing resources used by the system. Writes any changes to disk.

Returns:: MA_PIM_ERR_NONE on success. MA_PIM_ERR_HANDLE_INVALID if the item handle is invalid, or if the item's list is closed.

Note:: An item can also be closed by maPimItemRemove().

Warning:: Does not write changes to disk if the item's List is closed. Make sure to keep the List open while editing items.

References maIOCtl().

MAHandle maPimItemCreate ( MAHandle list )

Creates a new empty item in the specified list.

Returns:: >= 0 A handle to the new item. < 0 on error: MA_PIM_ERR_HANDLE_INVALID if the list handle is invalid.

Note:: The handle must be closed with maPimItemClose() to avoid memory leaks.

References maIOCtl().

int maPimItemRemove	(	MAHandle	list,
		MAHandle	item
	)

Removes an item from a list. This also has the effect of closing the item.

See also:: maPimItemClose()

Returns:: MA_PIM_ERR_NONE on success. MA_PIM_ERR_HANDLE_INVALID if the list handle or item handle are invalid.

Note:: If this function fails, the item is not closed.

References maIOCtl().

Classes

Typedefs

Functions

Typedef Documentation

Function Documentation