vcardstructured.h File Reference

Defines the data structure representing vCard structured values. More...

Go to the source code of this file.

Typedefs
typedef struct vcardstructuredtype_impl	vcardstructuredtype
	Represents a decoded, structured text value. More...

Functions
char *	vcardstructured_as_vcard_string_r (const vcardstructuredtype *st, bool is_param)
	Formats a vcardstructuredtype as a vCard property or parameter value. More...
vcardstructuredtype *	vcardstructured_clone (const vcardstructuredtype *st)
	Clones a vcardstructuredtype. More...
vcardstrarray *	vcardstructured_field_at (const vcardstructuredtype *st, size_t position)
	Returns the field at the given position in a vcardstructuredtype. More...
vcardstructuredtype *	vcardstructured_new (size_t num_fields)
	Creates a new instance of vcardstructuredtype. More...
vcardstructuredtype *	vcardstructured_new_from_string (const char *s)
	Creates a new instance of vcardstructuredtype from a string. More...
size_t	vcardstructured_num_fields (const vcardstructuredtype *st)
	Returns the number of fields in a vcardstructuredtype. More...
void	vcardstructured_ref (vcardstructuredtype *st)
	Increments the reference count of the vcardstructuredtype. More...
void	vcardstructured_set_field_at (vcardstructuredtype *st, size_t position, vcardstrarray *field)
	Sets the field at the given position in a vcardstructuredtype. More...
void	vcardstructured_set_num_fields (vcardstructuredtype *st, size_t num_fields)
	Sets the number of fields in a vcardstructuredtype. More...
void	vcardstructured_unref (vcardstructuredtype *st)
	Decrements the reference count of the vcardstructuredtype. More...

Detailed Description

Defines the data structure representing vCard structured values.

Definition in file vcardstructured.h.

Typedef Documentation

typedef struct vcardstructuredtype_impl vcardstructuredtype

Represents a decoded, structured text value.

vCard defines structured values for properties such as N and ADR. These values consist of "components", where each component may contain multiple values.

To avoid confusion with existing libical terminology, the vcardstructuredtype uses the term "field" to refer to a "component". A vcardstructuredtype consists of zero or more fields, each of which consists of zero or more values. A field is represented by a vcardstrarray. A field of value NULL is treated equally to an empty vcardstrarray.

Ownership

A vcardstructuredtype is reference counted, but its fields are not. Callers may read and alter the contents of fields, but they must not free a field other than by calling vcardstructured_set_field_at() with a NULL field value.

Definition at line 42 of file vcardstructured.h.

Function Documentation

char* vcardstructured_as_vcard_string_r	(	const vcardstructuredtype *	st,
		bool	is_param
	)

Formats a vcardstructuredtype as a vCard property or parameter value.

Parameters

st	The structured type object to format.
is_param	Whether the value is being formatted as a parameter value.

Returns

A newly allocated string representation, or NULL on error.

Ownership

The caller is responsible for freeing the returned string.

Definition at line 780 of file vcardvalue.c.

vcardstructuredtype* vcardstructured_clone

(

const vcardstructuredtype *

st

)

Clones a vcardstructuredtype.

Parameters

st	The object to clone.

See also

vcardstructuredtype_unref()

Error handling

If st is NULL it sets icalerrno to ICAL_BADARG_ERROR.

Ownership

The clone is a deep copy of st. The returned value has refcount 1. It is the caller's responsibility to call vcardstructuredtype_unref() after it's no longer used.

Definition at line 134 of file vcardstructured.c.

vcardstrarray* vcardstructured_field_at	(	const vcardstructuredtype *	st,
		size_t	position
	)

Returns the field at the given position in a vcardstructuredtype.

Parameters

st	The structured type object.
position	The zero-based index of the field to retrieve.

Returns

The vcardstrarray at position, or NULL on error.

Error handling

If st is NULL or position is out of bounds, it sets icalerrno to ICAL_BADARG_ERROR and returns NULL.

Definition at line 190 of file vcardstructured.c.

vcardstructuredtype* vcardstructured_new

(

size_t

num_fields

)

Creates a new instance of vcardstructuredtype.

Parameters

num_fields

The initial number of fields.

See also

vcardstructuredtype_unref()

Ownership

The returned value has refcount 1. It is the caller's responsibility to call vcardstructuredtype_unref() after it's no longer used.

Definition at line 65 of file vcardstructured.c.

vcardstructuredtype* vcardstructured_new_from_string

(

const char *

s

)

Creates a new instance of vcardstructuredtype from a string.

Parameters

s	The string containing a vCard representation of the structured value.

See also

vcardstructuredtype_unref()

Ownership

The returned value has refcount 1. It is the caller's responsibility to call vcardstructuredtype_unref() after it's no longer used.

Definition at line 77 of file vcardstructured.c.

size_t vcardstructured_num_fields

(

const vcardstructuredtype *

st

)

Returns the number of fields in a vcardstructuredtype.

Parameters

st	The structured type object.

Returns

The number of fields

Error handling

If st is NULL, it sets icalerrno to ICAL_BADARG_ERROR and returns 0.

Definition at line 152 of file vcardstructured.c.

void vcardstructured_ref

(

vcardstructuredtype *

st

)

Increments the reference count of the vcardstructuredtype.

Parameters

st	The object to increase the reference count of

See also

vcardstructuredtype_unref()

Error handling

If st is NULL, or the reference count is smaller than 0, it sets icalerrno to ICAL_BADARG_ERROR.

Ownership

By increasing the refcount of st, you are signaling that you are using it, and it is the owner's responsibility to call vcardstructuredtype_unref() after it's no longer used.

Definition at line 113 of file vcardstructured.c.

void vcardstructured_set_field_at	(	vcardstructuredtype *	st,
		size_t	position,
		vcardstrarray *	field
	)

Sets the field at the given position in a vcardstructuredtype.

Parameters

st	The structured type object.
position	The zero-based index of the field to set.
field	The vcardstrarray to store at position.

If position is beyond the current number of fields, the number of fields is extended to accommodate it. Any existing field at position is freed before being replaced.

Error handling

If st is NULL, it sets icalerrno to ICAL_BADARG_ERROR.

Definition at line 199 of file vcardstructured.c.

void vcardstructured_set_num_fields	(	vcardstructuredtype *	st,
		size_t	num_fields
	)

Sets the number of fields in a vcardstructuredtype.

Parameters

st	The structured type object.
num_fields	The new number of fields.

If num_fields is smaller than the current number of fields, the excess fields are freed.

Error handling

If st is NULL, it sets icalerrno to ICAL_BADARG_ERROR.

Definition at line 158 of file vcardstructured.c.

void vcardstructured_unref

(

vcardstructuredtype *

st

)

Decrements the reference count of the vcardstructuredtype.

Parameters

st	The object to decrease the reference count of

See also

vcardstructuredtype_ref()

Decreases the reference count of st. If this was the last user of the object, it is freed.

Error handling

If s is NULL, or the reference count is smaller than 0, it sets icalerrno to ICAL_BADARG_ERROR.

Ownership

Calling this function releases the vcardstructuredtype back to the library, and it must not be used afterwards.

Definition at line 120 of file vcardstructured.c.