vcardparameter.h File Reference

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

Go to the source code of this file.

Functions
void	vcardparameter_add_value_from_string (vcardparameter *param, const char *val)
char *	vcardparameter_as_vcard_string (vcardparameter *parameter)
	Converts vcardparameter into a string representation.
char *	vcardparameter_as_vcard_string_r (vcardparameter *parameter)
	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 *parameter)
	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.
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 *param)
bool	vcardparameter_kind_is_valid (const vcardparameter_kind kind)
	Checks the validity of a vcardparameter_kind.
const char *	vcardparameter_kind_to_string (vcardparameter_kind kind)
	Returns a string representing the given vcardparameter_kind.
vcardvalue_kind	vcardparameter_kind_value_kind (const vcardparameter_kind kind, int *is_multivalued)
vcardparameter *	vcardparameter_new (vcardparameter_kind kind)
	Creates new vcardparameter object.
vcardparameter *	vcardparameter_new_from_string (const char *str)
	Creates new vcardparameter object from string.
vcardparameter *	vcardparameter_new_from_value_string (vcardparameter_kind kind, const char *value)
	Creates new vcardparameter of a given kind with a given value.
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_value_from_string (vcardparameter *param, const char *val)
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.
vcardparameter_kind	vcardparameter_string_to_kind (const char *string)
	Returns the vcardparameter_kind for a given string.

Detailed Description

Defines the data structure representing vCard parameters.

Definition in file vcardparameter.h.

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);

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);

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);

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);

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);

Definition at line 368 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);

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);

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);

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_kind_is_valid()

bool vcardparameter_kind_is_valid

(

const vcardparameter_kind

kind

)

Checks the validity of a vcardparameter_kind.

Parameters

kind	The vcardparameter_kind

Returns

true if kind is valid, false otherwise

Usage

assert(vcardparameter_kind_is_valid(ICAL_ROLE_PARAMETER));

Since

3.0.4

vcardparameter_kind_to_string()

const char * vcardparameter_kind_to_string

(

vcardparameter_kind

kind

)

Returns a string representing the given vcardparameter_kind.

Parameters

kind	The vcardparameter_kind

Returns

A string representing kind

Error handling

When passed a non-existing vcardparameter_kind, it returns NULL.

Ownership

The string that is returned by this function is owned by libical and must not be freed by the caller.

Usage

assert(0 == strcmp(vcardparameter_kind_to_string(ICAL_ROLE_PARAMETER), "ROLE"));
assert(0 == strcmp(vcardparameter_kind_to_string(ICAL_EMAIL_PARAMETER), "EMAIL));
assert(0 == strcmp(vcardparameter_kind_to_string(ICAL_ID_PARAMETER), "ID"));

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_from_value_string()

vcardparameter * vcardparameter_new_from_value_string	(	vcardparameter_kind	kind,
		const char *	value )

Creates new vcardparameter of a given kind with a given value.

Parameters

kind	The kind of vcardparameter to create
value	The value of the parameter

Returns

An vcardparameter with the given kind and value.

Error handling

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

Ownership

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

Example

// create new parameter
vcardparameter *param;
param = vcardparameter_new_from_value_string(ICAL_ROLE_PARAMETER, "CHAIR");
 
// check parameter
assert(0 == strcmp(vcardparameter_get_iana_name(param), "ROLE"));
assert(0 == strcmp(vcardparameter_get_iana_value(param), "CHAIR"));
 
// release memory
vcardparameter_free(param);

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_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.

vcardparameter_string_to_kind()

vcardparameter_kind vcardparameter_string_to_kind

(

const char *

string

)

Returns the vcardparameter_kind for a given string.

Parameters

string

A string describing an vcardparameter_kind

Returns

An vcardparameter_kind

Error handling

Returns ICAL_NO_PARAMETER if string is NULL. If it can't find the parameter, depending on the ical_get_unknown_token_handling_setting(), it returns either ICAL_NO_PARAMETER or ICAL_IANA_PARAMETER.

Ownership

Does not take ownership of string.

Usage

assert(vcardparameter_string_to_kind("ROLE")  == ICAL_ROLE_PARAMETER);
assert(vcardparameter_string_to_kind("EMAIL") == ICAL_EMAIL_PARAMETER);
assert(vcardparameter_string_to_kind("ID")    == ICAL_ID_PARAMETER);