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

Functions
char *	icalparameter_as_ical_string (icalparameter *param)
	Converts icalparameter into a string representation. More...

char *	icalparameter_as_ical_string_r (icalparameter *param)
	Converts icalparameter into a string representation according to RFC5445/RFC6868. More...

icalparameter *	icalparameter_clone (const icalparameter *old)
	Creates new icalparameter as a clone of the given one. More...

void	icalparameter_decode_value (char *value)

void	icalparameter_free (icalparameter *param)
	Frees an icalparameter object. More...

const char *	icalparameter_get_iana_name (const icalparameter *param)
	Returns the IANA name of param. More...

const char *	icalparameter_get_iana_value (const icalparameter *param)
	Returns the IANA value of param. More...

icalproperty *	icalparameter_get_parent (const icalparameter *param)

const char *	icalparameter_get_xname (const icalparameter *param)
	Returns the X-name of param. More...

const char *	icalparameter_get_xvalue (const icalparameter *param)
	Returns the X-value of param. More...

bool	icalparameter_has_same_name (const icalparameter param1, const icalparameter param2)
	Determines if two parameters have the same name. More...

bool	icalparameter_is_multivalued (const icalparameter *param)

icalparameter_kind	icalparameter_isa (const icalparameter *parameter)

bool	icalparameter_isa_parameter (void *parameter)

icalparameter *	icalparameter_new (icalparameter_kind kind)
	Creates new icalparameter object. More...

icalparameter *	icalparameter_new_from_string (const char *str)
	Creates new icalparameter object from string. More...

void	icalparameter_set_iana_name (icalparameter param, const char v)
	Sets the IANA name of param to v. More...

void	icalparameter_set_iana_value (icalparameter param, const char v)
	Sets the IANA value of param to v. More...

void	icalparameter_set_parent (icalparameter param, icalproperty property)

void	icalparameter_set_xname (icalparameter param, const char v)
	Sets the X-name of param to v. More...

void	icalparameter_set_xvalue (icalparameter param, const char v)
	Sets the X-value of param to v. More...

Detailed Description

Implements the data structure representing iCalendar parameters.

Definition in file icalparameter.c.

Function Documentation

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

```c icalparameter *param = icalparameter_new_from_string("ROLE=CHAIR");

if(param) { printf("%s\n", icalparameter_as_ical_string(param)); }

icalparameter_free(param);
```

Definition at line 179 of file icalparameter.c.

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

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

Definition at line 197 of file icalparameter.c.

icalparameter* icalparameter_clone ( const icalparameter * old )

Creates new icalparameter as a clone of the given one.

Parameters

old	The existing, non-`NULL` parameter to clone.

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

Usage

```x // 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

Definition at line 86 of file icalparameter.c.

void icalparameter_decode_value ( char * value )

Decode the specified char string as a parameter value per RFC6868.

Parameters

value is a pointer to the char string to decode.

value will contain the decoded value on return. No error checking is performed.

Since: 4.0

Definition at line 413 of file icalparameter.c.

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

```c icalparameter *param = icalparameter_new();

if(param) { // use param... }

// after use, release it icalparameter_free(param);
```

Definition at line 58 of file icalparameter.c.

const char* icalparameter_get_iana_name ( const 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

```c // 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);
```

Definition at line 354 of file icalparameter.c.

const char* icalparameter_get_iana_value ( const 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

```c // 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);
```

Definition at line 344 of file icalparameter.c.

icalproperty* icalparameter_get_parent ( const icalparameter * param )

Gets the parent icalproperty of an icalparameter.

Parameters

param a pointer to the icalparameter

Returns: the parent icalproperty for the specified icalparameter.

Since: 3.0

Definition at line 366 of file icalparameter.c.

const char* icalparameter_get_xname ( const 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

```c // 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);
```

Definition at line 312 of file icalparameter.c.

const char* icalparameter_get_xvalue ( const 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

```c // 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);
```

Definition at line 332 of file icalparameter.c.

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

```c // 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);
```

Definition at line 373 of file icalparameter.c.

bool icalparameter_is_multivalued ( const icalparameter * param )

Return if the specified parameter is multivalued.

Parameters

param is a pointer to the icalparameter.

Returns: true if the specified parameter is multivalued; false otherwise.

Since: 4.0

Definition at line 406 of file icalparameter.c.

icalparameter_kind icalparameter_isa ( const 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);

Definition at line 279 of file icalparameter.c.

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

```c // 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);
```

Definition at line 288 of file icalparameter.c.

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

```c // create new parameter icalparameter *parameter = icalparameter_new();

if(parameter) { // use parameter ... }

// release parameter icalparameter_free(parameter);
```

Definition at line 51 of file icalparameter.c.

icalparameter* icalparameter_new_from_string ( const char * str )

Creates new icalparameter object from string.

Parameters

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

Usage

```c icalparameter *param = icalparameter_new_from_string("ROLE=CHAIR");

if(param) { // use param ... }

icalparameter_free(param);
```

Definition at line 130 of file icalparameter.c.

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

```c // 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);
```

Definition at line 349 of file icalparameter.c.

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

```c // 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);
```

Definition at line 339 of file icalparameter.c.

void icalparameter_set_parent	(	icalparameter *	param,
		icalproperty *	property
	)

Sets the parent icalproperty for the specified icalparameter.

Parameters

param	a pointer to a valid icalparameter
property	a pointer to a presumably valid icalproperty to use

Since: 3.0

Definition at line 359 of file icalparameter.c.

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

```c // 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);
```

Definition at line 299 of file icalparameter.c.

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

```c // 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);
```

Definition at line 319 of file icalparameter.c.

Libical API Documentation 4.0 STABLE VERSION Visit the v3.0 documentation

Functions

Detailed Description

Function Documentation