Implements the data structure representing vCard parameters. More...

Macros
#define	VCARD_INTEGER_LENGTH 21

Functions
char *	vcardparameter_as_vcard_string (vcardparameter *param)
	Converts vcardparameter into a string representation.
char *	vcardparameter_as_vcard_string_r (vcardparameter *param)
	Converts vcardparameter into an string representation according to RFC5445/RFC6868.
vcardparameter *	vcardparameter_clone (const vcardparameter *old)
	Creates new vcardparameter as a clone of the given one.
void	vcardparameter_free (vcardparameter *param)
	Frees an vcardparameter object.
const char *	vcardparameter_get_iana_name (const vcardparameter *param)
	Returns the IANA name of param.
const char *	vcardparameter_get_iana_value (const vcardparameter *param)
	Returns the IANA value of param.
vcardproperty *	vcardparameter_get_parent (const vcardparameter *param)
const char *	vcardparameter_get_xname (const vcardparameter *param)
	Returns the X-name of param.
const char *	vcardparameter_get_xvalue (const vcardparameter *param)
	Returns the X-value of param.
bool	vcardparameter_has_same_name (const vcardparameter param1, const vcardparameter param2)
	Determines if two parameters have the same name.
bool	vcardparameter_is_multivalued (const vcardparameter *param)
bool	vcardparameter_is_structured (const vcardparameter *param)
vcardparameter_kind	vcardparameter_isa (const vcardparameter *parameter)
bool	vcardparameter_isa_parameter (void *parameter)
vcardparameter *	vcardparameter_new (vcardparameter_kind kind)
	Creates new vcardparameter object.
vcardparameter *	vcardparameter_new_from_string (const char *str)
	Creates new vcardparameter object from string.
struct vcardparameter_impl *	vcardparameter_new_impl (vcardparameter_kind kind)
void	vcardparameter_set_iana_name (vcardparameter param, const char v)
	Sets the IANA name of param to v.
void	vcardparameter_set_iana_value (vcardparameter param, const char v)
	Sets the IANA value of param to v.
void	vcardparameter_set_parent (vcardparameter param, vcardproperty property)
void	vcardparameter_set_xname (vcardparameter param, const char v)
	Sets the X-name of param to v.
void	vcardparameter_set_xvalue (vcardparameter param, const char v)
	Sets the X-value of param to v.

Detailed Description

Implements the data structure representing vCard parameters.

Definition in file vcardparameter.c.

Function Documentation

◆ vcardparameter_as_vcard_string()

char * vcardparameter_as_vcard_string ( vcardparameter * parameter )

Converts vcardparameter into a string representation.

Parameters

parameter The vcardparameter to convert

Returns: A string representing the parameter according to RFC5445/RFC6868.

See also: vcardparameter_as_ical_string_r()

Error handling: If there is any error, the method returns NULL. Furthermore, if parameter is NULL, it also sets icalerrno to ICAL_BADARG_ERROR. If it doesn't recognize the kind of the parameter, it sets icalerrno it ICAL_BADARG_ERROR. If the parameter is otherwise malformed, it sets icalerrno to ICAL_MALFORMEDDATA_ERROR.

Ownership: Strings returned by this method are owned by libical, they must not be freed and they may be reclaimed with the next call into the library. A version of this function, which returns strings that are not owned by libical, is vcardparameter_as_ical_string_r().

Usage: vcardparameter *param = vcardparameter_new_from_string("ROLE=CHAIR");

if(param) {

printf("%s\n", vcardparameter_as_ical_string(param));

}

vcardparameter_free(param);

vcardparameter_new_from_string
vcardparameter * vcardparameter_new_from_string(const char *str)
Creates new vcardparameter object from string.
Definition vcardparameter.c:125

vcardparameter_free
void vcardparameter_free(vcardparameter *param)
Frees an vcardparameter object.
Definition vcardparameter.c:52

Definition at line 174 of file vcardparameter.c.

◆ vcardparameter_as_vcard_string_r()

char * vcardparameter_as_vcard_string_r ( vcardparameter * parameter )

Converts vcardparameter into an string representation according to RFC5445/RFC6868.

Parameters

parameter The vcardparameter to convert

Returns: A string representing the parameter

See also: vcardparameter_as_ical_string()

Error handling: If there is any error, the method returns NULL. Furthermore, if parameter is NULL, it also sets icalerrno to ICAL_BADARG_ERROR. If it doesn't recognize the kind of the parameter, it sets icalerrno to ICAL_BADARG_ERROR. If the parameter is otherwise malformed, it sets icalerrno to ICAL_MALFORMEDDATA_ERROR.

Ownership: Strings returned by this method are owned by the caller, thus they need to be manually icalmemory_free_buffer()d after use. A version of this function which returns strings that do not need to be freed manually is vcardparameter_as_ical_string().

Usage: vcardparameter *param = vcardparameter_new_from_string("ROLE=CHAIR");

if(param) {

char *str = vcardparameter_as_ical_string(param);

printf("%s\n", str);

icalmemory_free_buffer(str);

}

vcardparameter_free(param);

icalmemory_free_buffer
void icalmemory_free_buffer(void *buf)
Releases a buffer.
Definition icalmemory.c:353

Definition at line 192 of file vcardparameter.c.

◆ vcardparameter_clone()

vcardparameter * vcardparameter_clone ( const vcardparameter * old )

Creates new vcardparameter as a clone of the given one.

Parameters

old	The existing, non-NULL parameter to clone.

Returns: An vcardparameter that is a clone of the given one.

Error handling: If old is NULL, it returns NULL and sets icalerrno to ICAL_BADARG_ERROR. If there was an internal error cloning the data, it returns NULL without reporting any error in icalerrno.

Ownership: Objects created by this method are owned by the caller and must be released with the vcardparameter_free() method.

Usage: // create an vcardparameter

vcardparameter *param = vcardparameter_new_from_string("ROLE=CHAIR");

// clone the parameter

vcardparameter *clone = vcardparameter_clone(param);

if(clone) {

// use clone ...

}

// release parameters

vcardparameter_free(param);

vcardparameter_free(clone);

Since: 4.0

Definition at line 81 of file vcardparameter.c.

◆ vcardparameter_free()

void vcardparameter_free ( vcardparameter * parameter )

Frees an vcardparameter object.

Parameters

parameter The vcardparameter to free

This method needs to be used on all parameter objects returned from any of the _new() methods including vcardparameter_new(), vcardparameter_new_from_string() and vcardparameter_new_from_value_string() and on cloned parameter objects returned by vcardparameter_clone() when these object are not needed anymore and to be released.

Usage: vcardparameter *param = vcardparameter_new();

if(param) {

// use param...

}

// after use, release it

vcardparameter_free(param);

vcardparameter_new
vcardparameter * vcardparameter_new(vcardparameter_kind kind)
Creates new vcardparameter object.
Definition vcardparameter.c:45

Definition at line 52 of file vcardparameter.c.

◆ vcardparameter_get_iana_name()

const char * vcardparameter_get_iana_name ( const vcardparameter * param )

Returns the IANA name of param.

Parameters

param The vcardparameter whose IANA name is to be returned

Returns: A string representing the IANA name of param

See also: vcardparameter_set_iana_name()

Error handling: Returns NULL and sets icalerrno to ICAL_BADARG_ERROR when a NULL is passed instead of an vcardparameter.

Ownership: The string that is returned stays owned by libical and must not be freed by the caller.

Usage: // creates new parameter

vcardparameter *param = vcardparameter_new();

// sets iana name

vcardparameter_set_iana_name(param, "X-TEST");

// compare iana name

assert(0 == strcmp(vcardparameter_get_iana_name(param), "X-TEST"));

vcardparameter_free(param);

vcardparameter_get_iana_name
const char * vcardparameter_get_iana_name(const vcardparameter *param)
Returns the IANA name of param.
Definition vcardparameter.c:378

vcardparameter_set_iana_name
void vcardparameter_set_iana_name(vcardparameter *param, const char *v)
Sets the IANA name of param to v.
Definition vcardparameter.c:373

Definition at line 378 of file vcardparameter.c.

◆ vcardparameter_get_iana_value()

const char * vcardparameter_get_iana_value ( const vcardparameter * param )

Returns the IANA value of param.

Parameters

param The vcardparameter whose value is to be returned

Returns: A string representing the value of param

See also: vcardparameter_set_iana_value()

Error handling: Returns NULL and sets icalerrno to ICAL_BADARG_ERROR when a NULL is passed instead of an vcardparameter.

Ownership: The string that is returned stays owned by libical and must not be freed by the caller.

Usage: // create new parameter

vcardparameter *param = vcardparameter_new_from_string("ROLE=ATTENDEE");

// set role to chair

vcardparameter_set_iana_value(param, "CHAIR");

// check that it worked

assert(0 == strcmp(vcardparameter_get_iana_value(param), "SUCCESS"));

// release memory

vcardparameter_free(param);

vcardparameter_get_iana_value
const char * vcardparameter_get_iana_value(const vcardparameter *param)
Returns the IANA value of param.
Definition vcardparameter.c:368

vcardparameter_set_iana_value
void vcardparameter_set_iana_value(vcardparameter *param, const char *v)
Sets the IANA value of param to v.
Definition vcardparameter.c:363

Definition at line 368 of file vcardparameter.c.

◆ vcardparameter_get_parent()

vcardproperty * vcardparameter_get_parent ( const vcardparameter * param )

Returns the parent vcardproperty for the specified vcardparameter.

Since: 3.0

Definition at line 390 of file vcardparameter.c.

◆ vcardparameter_get_xname()

const char * vcardparameter_get_xname ( const vcardparameter * param )

Returns the X-name of param.

Parameters

param The vcardparameter whose X-name is to be returned

Returns: A string representing the X-name of param

See also: vcardparameter_set_xname()

Error handling: Returns NULL and sets icalerrno to ICAL_BADARG_ERROR when a NULL is passed instead of an vcardparameter.

Ownership: The string that is returned stays owned by libical and must not be freed by the caller.

Usage: // creates new parameter

vcardparameter *param = vcardparameter_new();

// sets xname

vcardparameter_set_xname(param, "X-TEST");

// compare xname

assert(0 == strcmp(vcardparameter_get_xname(param), "X-TEST"));

vcardparameter_free(param);

vcardparameter_set_xname
void vcardparameter_set_xname(vcardparameter *param, const char *v)
Sets the X-name of param to v.
Definition vcardparameter.c:317

vcardparameter_get_xname
const char * vcardparameter_get_xname(const vcardparameter *param)
Returns the X-name of param.
Definition vcardparameter.c:333

Definition at line 333 of file vcardparameter.c.

◆ vcardparameter_get_xvalue()

const char * vcardparameter_get_xvalue ( const vcardparameter * param )

Returns the X-value of param.

Parameters

param The vcardparameter whose X-value is to be returned

Returns: A string representing the X-value of param

See also: vcardparameter_set_xvalue()

Error handling: Returns NULL and sets icalerrno to ICAL_BADARG_ERROR when a NULL is passed instead of an vcardparameter.

Ownership: The string that is returned stays owned by libical and must not be freed by the caller.

Usage: // create new parameter

vcardparameter *param = vcardparameter_new_from_string("X-TEST=FAIL");

// set test to success

vcardparameter_set_xvalue(param, "SUCCESS");

// check that it worked

assert(0 == strcmp(vcardparameter_get_xvalue(param), "SUCCESS"));

// release memory

vcardparameter_free(param);

vcardparameter_set_xvalue
void vcardparameter_set_xvalue(vcardparameter *param, const char *v)
Sets the X-value of param to v.
Definition vcardparameter.c:340

vcardparameter_get_xvalue
const char * vcardparameter_get_xvalue(const vcardparameter *param)
Returns the X-value of param.
Definition vcardparameter.c:356

Definition at line 356 of file vcardparameter.c.

◆ vcardparameter_has_same_name()

bool vcardparameter_has_same_name	(	const vcardparameter *	param1,
		const vcardparameter *	param2 )

Determines if two parameters have the same name.

Parameters

param1	First parameter to compare
param2	Second parameter to compare

Returns: true if they have the same name, false otherwise.

Error handling: If either of param1 or param2 are NULL, it returns 0 and sets icalerrno to ICAL_BADARG_ERROR.

Ownership: Does not take ownership of either vcardparameter.

Example: // create two parameters

vcardparameter *param1 = vcardparameter_new_from_string("ROLE=CHAIR");

vcardparameter *param2 = vcardparameter_new_from_string("EMAIL=mailto@example.com");

// compare parameter names for equality

assert(vcardparameter_has_same_name(param1, param2) == 0);

// release memory

vcardparameter_free(param1);

vcardparameter_free(param2);

vcardparameter_has_same_name
bool vcardparameter_has_same_name(const vcardparameter *param1, const vcardparameter *param2)
Determines if two parameters have the same name.
Definition vcardparameter.c:397

Definition at line 397 of file vcardparameter.c.

◆ vcardparameter_is_multivalued()

bool vcardparameter_is_multivalued ( const vcardparameter * param )

Definition at line 430 of file vcardparameter.c.

◆ vcardparameter_is_structured()

bool vcardparameter_is_structured ( const vcardparameter * param )

Definition at line 437 of file vcardparameter.c.

◆ vcardparameter_isa()

vcardparameter_kind vcardparameter_isa ( const vcardparameter * parameter )

Returns the vcardparameter_kind of parameter.

Parameters

parameter The vcardparameter whose kind to determine

Returns: The vcardparameter_kind of the parameter

Error handling Returns ICAL_NO_PARAMETER when passed NULL.

Usage

// create parameter
vcardparameter *param = vcardparameter_new_from_string("ROLE=CHAIR");
 
// check what type of parameter this is
assert(vcardparameter_isa(param) == ICAL_ROLE_PARAMETER);
 
// release memory
vcardparameter_free(param);

Definition at line 293 of file vcardparameter.c.

◆ vcardparameter_isa_parameter()

bool vcardparameter_isa_parameter ( void * param )

Determines if the given param is an vcardparameter

Parameters

param The libical-originated object to check

Returns: true if the object is an vcardparameter, false otherwise.

Note: This function expects to be given an object originating from libical - if this function is passed anything that is not from libical, its behavior is undefined.

Error handling When given a NULL object, it returns 0.

Usage

// create parameter
vcardparameter *param = vcardparameter_new_from_string("ROLE=CHAIR");
 
// check if it's a parameter
assert(vcardparameter_isa_parameter(param));
 
// release memory
vcardparameter_free(param);

Definition at line 302 of file vcardparameter.c.

◆ vcardparameter_new()

vcardparameter * vcardparameter_new ( vcardparameter_kind kind )

Creates new vcardparameter object.

Parameters

kind	The kind of vcardparameter to create.

Returns: An vcardparameter with the given kind.

Error handling: If there was an internal error regarding memory allocation, it returns NULL and sets icalerrno to ICAL_NEWFAILED_ERROR.

Ownership: Objects created by this method are owned by the caller and must be released with the vcardparameter_free() method.

Usage: // create new parameter

vcardparameter *parameter = vcardparameter_new();

if(parameter) {

// use parameter ...

}

// release parameter

vcardparameter_free(parameter);

Definition at line 45 of file vcardparameter.c.

◆ vcardparameter_new_from_string()

vcardparameter * vcardparameter_new_from_string ( const char * str )

Creates new vcardparameter object from string.

Parameters

str	The string from which to create the vcardparameter, in the form "PARAMNAME=VALUE"

Returns: An vcardparameter that corresponds to the given string.

Error handling: If there was an internal error copying data, it returns NULL and sets icalerrno to ICAL_NEWFAILED_ERROR. If str was NULL, it returns NULL and sets icalerrno to ICAL_BADARG_ERROR. If str was malformed, it returns NULL and sets icalerrno to ICAL_MALFORMEDDATA_ERROR.

Ownership: Objects created by this method are owned by the caller and must be released with the vcardparameter_free() method.

Usage: vcardparameter *param = vcardparameter_new_from_string("ROLE=CHAIR");

if(param) {

// use param ...

}

vcardparameter_free(param);

Definition at line 125 of file vcardparameter.c.

◆ vcardparameter_new_impl()

struct vcardparameter_impl * vcardparameter_new_impl ( vcardparameter_kind kind )

Definition at line 26 of file vcardparameter.c.

◆ vcardparameter_set_iana_name()

void vcardparameter_set_iana_name	(	vcardparameter *	param,
		const char *	v )

Sets the IANA name of param to v.

Parameters

param	The vcardparameter to change
v	The IANA name to set param to

See also: vcardparameter_get_iana_name()

Error handling: If either param or v are NULL, it sets :calerrno to ICAL_BARARG_ERROR. If there is an error acquiring memory, it sets errno to ENOMEM.

Ownership: The passed string v stays in the ownership of the caller - libical creates a copy of it.

Usage: // creates new parameter

vcardparameter *param = vcardparameter_new();

// sets iana name

vcardparameter_set_iana_name(param, "ROLE");

// compare iana name

assert(0 == strcmp(vcardparameter_get_iana_name(param), "X-TEST"));

vcardparameter_free(param);

Definition at line 373 of file vcardparameter.c.

◆ vcardparameter_set_iana_value()

void vcardparameter_set_iana_value	(	vcardparameter *	param,
		const char *	v )

Sets the IANA value of param to v.

Parameters

param	The vcardparameter to change
v	The IANA value to set param to

See also: vcardparameter_get_iana_value()

Error handling: If either param or v are NULL, it sets icalerrno to ICAL_BARARG_ERROR. If there is an error acquiring memory, it sets errno to ENOMEM.

Ownership: The passed string v stays in the ownership of the caller - libical creates a copy of it.

Usage: // create new parameter

vcardparameter *param = vcardparameter_new_from_string("ROLE=ATTENDEE");

// set role to chair

vcardparameter_set_iana_value(param, "CHAIR");

// check that it worked

assert(0 == strcmp(vcardparameter_get_iana_value(param), "SUCCESS"));

// release memory

vcardparameter_free(param);

Definition at line 363 of file vcardparameter.c.

◆ vcardparameter_set_parent()

void vcardparameter_set_parent	(	vcardparameter *	param,
		vcardproperty *	property )

Sets the parent vcardproperty for the specified vcardparameter.

Since: 3.0

Definition at line 383 of file vcardparameter.c.

◆ vcardparameter_set_xname()

void vcardparameter_set_xname	(	vcardparameter *	param,
		const char *	v )

Sets the X-name of param to v.

Parameters

param	The vcardparameter to change
v	The X-name to set param to

See also: vcardparameter_get_xname()

Error handling: If either param or v are NULL, it sets icalerrno to ICAL_BARARG_ERROR. If there is an error acquiring memory, it sets errno to ENOMEM.

Ownership: The passed string v stays in the ownership of the caller - libical creates a copy of it.

Usage: // creates new parameter

vcardparameter *param = vcardparameter_new();

// sets xname

vcardparameter_set_xname(param, "X-TEST");

// compare xname

assert(0 == strcmp(vcardparameter_get_xname(param), "X-TEST"));

vcardparameter_free(param);

Definition at line 317 of file vcardparameter.c.

◆ vcardparameter_set_xvalue()

void vcardparameter_set_xvalue	(	vcardparameter *	param,
		const char *	v )

Sets the X-value of param to v.

Parameters

param	The vcardparameter to change
v	The X-value to set param to

See also: vcardparameter_get_xvalue()

Error handling: If either param or v are NULL, it sets icalerrno to ICAL_BARARG_ERROR. If there is an error acquiring memory, it sets errno to ENOMEM.

Ownership: The passed string v stays in the ownership of the caller - libical creates a copy of it.

Usage: // create new parameter

vcardparameter *param = vcardparameter_new_from_string("X-TEST=FAIL");

// set test to success

vcardparameter_set_xvalue(param, "SUCCESS");

// check that it worked

assert(0 == strcmp(vcardparameter_get_xvalue(param), "SUCCESS"));

// release memory

vcardparameter_free(param);

Definition at line 340 of file vcardparameter.c.

Macros

Functions

Detailed Description

Function Documentation

◆ vcardparameter_as_vcard_string()

◆ vcardparameter_as_vcard_string_r()

◆ vcardparameter_clone()

◆ vcardparameter_free()

◆ vcardparameter_get_iana_name()

◆ vcardparameter_get_iana_value()

◆ vcardparameter_get_parent()

◆ vcardparameter_get_xname()

◆ vcardparameter_get_xvalue()

◆ vcardparameter_has_same_name()

◆ vcardparameter_is_multivalued()

◆ vcardparameter_is_structured()

◆ vcardparameter_isa()

◆ vcardparameter_isa_parameter()

◆ vcardparameter_new()

◆ vcardparameter_new_from_string()

◆ vcardparameter_new_impl()

◆ vcardparameter_set_iana_name()

◆ vcardparameter_set_iana_value()

◆ vcardparameter_set_parent()

◆ vcardparameter_set_xname()

◆ vcardparameter_set_xvalue()