icalparameter.h File Reference

Go to the source code of this file.

Functions
char *	icalparameter_as_ical_string (icalparameter *parameter)
	Converts icalparameter into a string representation.
char *	icalparameter_as_ical_string_r (icalparameter *parameter)
	Converts icalparameter into a string representation according to RFC5445/RFC6868.
icalparameter *	icalparameter_clone (const icalparameter *p)
	Creates new icalparameter as a clone of the given one.
void	icalparameter_free (icalparameter *parameter)
	Frees an icalparameter object.
const char *	icalparameter_get_iana_name (icalparameter *param)
	Returns the IANA name of param.
const char *	icalparameter_get_iana_value (icalparameter *param)
	Returns the IANA value of param.
const char *	icalparameter_get_xname (icalparameter *param)
	Returns the X-name of param.
const char *	icalparameter_get_xvalue (icalparameter *param)
	Returns the X-value of param.
bool	icalparameter_has_same_name (icalparameter *param1, icalparameter *param2)
	Determines if two parameters have the same name.
icalparameter_kind	icalparameter_isa (icalparameter *parameter)
bool	icalparameter_isa_parameter (void *param)
bool	icalparameter_kind_is_valid (const icalparameter_kind kind)
	Checks the validity of an icalparameter_kind.
const char *	icalparameter_kind_to_string (icalparameter_kind kind)
	Returns a string representing the given icalparameter_kind.
icalparameter *	icalparameter_new (icalparameter_kind kind)
	Creates new icalparameter object.
icalparameter *	icalparameter_new_from_string (const char *value)
	Creates new icalparameter object from string.
icalparameter *	icalparameter_new_from_value_string (icalparameter_kind kind, const char *value)
	Creates new icalparameter of a given kind with a given value.
void	icalparameter_set_iana_name (icalparameter *param, const char *v)
	Sets the IANA name of param to v.
void	icalparameter_set_iana_value (icalparameter *param, const char *v)
	Sets the IANA value of param to v.
void	icalparameter_set_xname (icalparameter *param, const char *v)
	Sets the X-name of param to v.
void	icalparameter_set_xvalue (icalparameter *param, const char *v)
	Sets the X-value of param to v.
icalparameter_kind	icalparameter_string_to_kind (const char *string)
	Returns the icalparameter_kind for a given string.

Detailed Description

Functions to work with ical parameter objects, which represent parameters to property objects.

Function Documentation

icalparameter_as_ical_string()

char * icalparameter_as_ical_string

(

icalparameter *

parameter

)

Converts icalparameter into a string representation.

Parameters

parameter

The icalparameter to convert

Returns

A string representing the parameter according to RFC5445/RFC6868.

See also

icalparameter_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 icalparameter_as_ical_string_r().

Usage

icalparameter *param = icalparameter_new_from_string("ROLE=CHAIR");
 
if(param) {
    printf("%s\n", icalparameter_as_ical_string(param));
}
 
icalparameter_free(param);

icalparameter_as_ical_string_r()

char * icalparameter_as_ical_string_r

(

icalparameter *

parameter

)

Converts icalparameter into a string representation according to RFC5445/RFC6868.

Parameters

parameter

The icalparameter to convert

Returns

A string representing the parameter

See also

icalparameter_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 icalparameter_as_ical_string().

Usage

icalparameter *param = icalparameter_new_from_string("ROLE=CHAIR");
 
if(param) {
    char *str = icalparameter_as_ical_string(param);
    printf("%s\n", str);
    icalmemory_free_buffer(str);
}
 
icalparameter_free(param);

icalparameter_clone()

icalparameter * icalparameter_clone

(

const icalparameter *

p

)

Creates new icalparameter as a clone of the given one.

Parameters

p	The existing, non-NULL parameter to clone.

Returns

An icalparameter that is a clone of the given one.

Error handling

If p 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 icalparameter_free() method.

Usage

// create an icalparameter
icalparameter *param = icalparameter_new_from_string("ROLE=CHAIR");
 
// clone the parameter
icalparameter *clone = icalparameter_clone(param);
 
if(clone) {
    // use clone ...
}
 
// release parameters
icalparameter_free(param);
icalparameter_free(clone);

Since

4.0

icalparameter_free()

void icalparameter_free

(

icalparameter *

parameter

)

Frees an icalparameter object.

Parameters

parameter

The icalparameter to free

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

Usage

icalparameter *param = icalparameter_new();
 
if(param) {
    // use param...
}
 
// after use, release it
icalparameter_free(param);

icalparameter_get_iana_name()

const char * icalparameter_get_iana_name

(

icalparameter *

param

)

Returns the IANA name of param.

Parameters

param

The icalparameter whose IANA name is to be returned

Returns

A string representing the IANA name of param

See also

icalparameter_set_iana_name()

Error handling

Returns NULL and sets icalerrno to ICAL_BADARG_ERROR when a NULL is passed instead of an icalparameter.

Ownership

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

Usage

// creates new parameter
icalparameter *param = icalparameter_new();
 
// sets iana name
icalparameter_set_iana_name(param, "X-TEST");
 
// compare iana name
assert(0 == strcmp(icalparameter_get_iana_name(param), "X-TEST"));
 
icalparameter_free(param);

icalparameter_get_iana_value()

const char * icalparameter_get_iana_value

(

icalparameter *

param

)

Returns the IANA value of param.

Parameters

param

The icalparameter whose value is to be returned

Returns

A string representing the value of param

See also

icalparameter_set_iana_value()

Error handling

Returns NULL and sets icalerrno to ICAL_BADARG_ERROR when a NULL is passed instead of an icalparameter.

Ownership

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

Usage

// create new parameter
icalparameter *param = icalparameter_new_from_string("ROLE=ATTENDEE");
 
// set role to chair
icalparameter_set_iana_value(param, "CHAIR");
 
// check that it worked
assert(0 == strcmp(icalparameter_get_iana_value(param), "SUCCESS"));
 
// release memory
icalparameter_free(param);

icalparameter_get_xname()

const char * icalparameter_get_xname

(

icalparameter *

param

)

Returns the X-name of param.

Parameters

param

The icalparameter whose X-name is to be returned

Returns

A string representing the X-name of param

See also

icalparameter_set_xname()

Error handling

Returns NULL and sets icalerrno to ICAL_BADARG_ERROR when a NULL is passed instead of an icalparameter.

Ownership

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

Usage

// creates new parameter
icalparameter *param = icalparameter_new();
 
// sets xname
icalparameter_set_xname(param, "X-TEST");
 
// compare xname
assert(0 == strcmp(icalparameter_get_xname(param), "X-TEST"));
 
icalparameter_free(param);

icalparameter_get_xvalue()

const char * icalparameter_get_xvalue

(

icalparameter *

param

)

Returns the X-value of param.

Parameters

param

The icalparameter whose X-value is to be returned

Returns

A string representing the X-value of param

See also

icalparameter_set_xvalue()

Error handling

Returns NULL and sets icalerrno to ICAL_BADARG_ERROR when a NULL is passed instead of an icalparameter.

Ownership

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

Usage

// create new parameter
icalparameter *param = icalparameter_new_from_string("X-TEST=FAIL");
 
// set test to success
icalparameter_set_xvalue(param, "SUCCESS");
 
// check that it worked
assert(0 == strcmp(icalparameter_get_xvalue(param), "SUCCESS"));
 
// release memory
icalparameter_free(param);

icalparameter_has_same_name()

bool icalparameter_has_same_name	(	icalparameter *	param1,
		icalparameter *	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 icalparameter.

Example

// create two parameters
icalparameter *param1 = icalparameter_new_from_string("ROLE=CHAIR");
icalparameter *param2 = icalparameter_new_from_string("EMAIL=mailto@example.com");
 
// compare parameter names for equality
assert(icalparameter_has_same_name(param1, param2) == 0);
 
// release memory
icalparameter_free(param1);
icalparameter_free(param2);

icalparameter_isa()

icalparameter_kind icalparameter_isa

(

icalparameter *

parameter

)

Returns the icalparameter_kind of parameter.

Parameters

parameter

The icalparameter whose kind to determine

Returns

The icalparameter_kind of the parameter

Error handling Returns ICAL_NO_PARAMETER when passed NULL.

Usage

// create parameter
icalparameter *param = icalparameter_new_from_string("ROLE=CHAIR");
 
// check what type of parameter this is
assert(icalparameter_isa(param) == ICAL_ROLE_PARAMETER);
 
// release memory
icalparameter_free(param);

icalparameter_isa_parameter()

bool icalparameter_isa_parameter

(

void *

param

)

Determines if the given param is an icalparameter

Parameters

param

The libical-originated object to check

Returns

true if the object is an icalparameter, 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
icalparameter *param = icalparameter_new_from_string("ROLE=CHAIR");
 
// check if it's a parameter
assert(icalparameter_isa_parameter(param));
 
// release memory
icalparameter_free(param);

icalparameter_kind_is_valid()

bool icalparameter_kind_is_valid

(

const icalparameter_kind

kind

)

Checks the validity of an icalparameter_kind.

Parameters

kind	The icalparameter_kind

Returns

true if kind is valid, false otherwise

Usage

assert(icalparameter_kind_is_valid(ICAL_ROLE_PARAMETER));

Since

3.0.4

icalparameter_kind_to_string()

const char * icalparameter_kind_to_string

(

icalparameter_kind

kind

)

Returns a string representing the given icalparameter_kind.

Parameters

kind	The icalparameter_kind

Returns

A string representing kind

Error handling

When passed a non-existing icalparameter_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(icalparameter_kind_to_string(ICAL_ROLE_PARAMETER), "ROLE"));
assert(0 == strcmp(icalparameter_kind_to_string(ICAL_EMAIL_PARAMETER), "EMAIL));
assert(0 == strcmp(icalparameter_kind_to_string(ICAL_ID_PARAMETER), "ID"));

icalparameter_new()

icalparameter * icalparameter_new

(

icalparameter_kind

kind

)

Creates new icalparameter object.

Parameters

kind	The kind of icalparameter to create.

Returns

An icalparameter 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 icalparameter_free() method.

Usage

// create new parameter
icalparameter *parameter = icalparameter_new();
 
if(parameter) {
    // use parameter ...
}
 
// release parameter
icalparameter_free(parameter);

icalparameter_new_from_string()

icalparameter * icalparameter_new_from_string

(

const char *

value

)

Creates new icalparameter object from string.

Parameters

value

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

Returns

An icalparameter 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 value was NULL, it returns NULL and sets icalerrno to ICAL_BADARG_ERROR. If value 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 icalparameter_free() method.

Usage

icalparameter *param = icalparameter_new_from_string("ROLE=CHAIR");
 
if(param) {
    // use param ...
}
 
icalparameter_free(param);

icalparameter_new_from_value_string()

icalparameter * icalparameter_new_from_value_string	(	icalparameter_kind	kind,
		const char *	value )

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

Parameters

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

Returns

An icalparameter 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 icalparameter_free() method.

Example

// create new parameter
icalparameter *param;
param = icalparameter_new_from_value_string(ICAL_ROLE_PARAMETER, "CHAIR");
 
// check parameter
assert(0 == strcmp(icalparameter_get_iana_name(param), "ROLE"));
assert(0 == strcmp(icalparameter_get_iana_value(param), "CHAIR"));
 
// release memory
icalparameter_free(param);

icalparameter_set_iana_name()

void icalparameter_set_iana_name	(	icalparameter *	param,
		const char *	v )

Sets the IANA name of param to v.

Parameters

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

See also

icalparameter_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
icalparameter *param = icalparameter_new();
 
// sets iana name
icalparameter_set_iana_name(param, "ROLE");
 
// compare iana name
assert(0 == strcmp(icalparameter_get_iana_name(param), "X-TEST"));
 
icalparameter_free(param);

icalparameter_set_iana_value()

void icalparameter_set_iana_value	(	icalparameter *	param,
		const char *	v )

Sets the IANA value of param to v.

Parameters

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

See also

icalparameter_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
icalparameter *param = icalparameter_new_from_string("ROLE=ATTENDEE");
 
// set role to chair
icalparameter_set_iana_value(param, "CHAIR");
 
// check that it worked
assert(0 == strcmp(icalparameter_get_iana_value(param), "SUCCESS"));
 
// release memory
icalparameter_free(param);

icalparameter_set_xname()

void icalparameter_set_xname	(	icalparameter *	param,
		const char *	v )

Sets the X-name of param to v.

Parameters

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

See also

icalparameter_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
icalparameter *param = icalparameter_new();
 
// sets xname
icalparameter_set_xname(param, "X-TEST");
 
// compare xname
assert(0 == strcmp(icalparameter_get_xname(param), "X-TEST"));
 
icalparameter_free(param);

icalparameter_set_xvalue()

void icalparameter_set_xvalue	(	icalparameter *	param,
		const char *	v )

Sets the X-value of param to v.

Parameters

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

See also

icalparameter_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
icalparameter *param = icalparameter_new_from_string("X-TEST=FAIL");
 
// set test to success
icalparameter_set_xvalue(param, "SUCCESS");
 
// check that it worked
assert(0 == strcmp(icalparameter_get_xvalue(param), "SUCCESS"));
 
// release memory
icalparameter_free(param);

icalparameter_string_to_kind()

icalparameter_kind icalparameter_string_to_kind

(

const char *

string

)

Returns the icalparameter_kind for a given string.

Parameters

string

A string describing an icalparameter_kind

Returns

An icalparameter_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(icalparameter_string_to_kind("ROLE")  == ICAL_ROLE_PARAMETER);
assert(icalparameter_string_to_kind("EMAIL") == ICAL_EMAIL_PARAMETER);
assert(icalparameter_string_to_kind("ID")    == ICAL_ID_PARAMETER);