Libical API Documentation 3.0

Functions
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. More...
char * | icalparameter_as_ical_string_r (icalparameter *parameter)
| Converts ::icalparameter into an string representation according to RFC5445/RFC6868. More...
void | icalparameter_free (icalparameter *parameter)
| Frees an ::icalparameter object. More...
const char * | icalparameter_get_iana_name (icalparameter *param)
| Returns the IANA name of param. More...
const char * | icalparameter_get_iana_value (icalparameter *param)
| Returns the IANA value of param. More...
const char * | icalparameter_get_xname (icalparameter *param)
| Returns the X-name of param. More...
const char * | icalparameter_get_xvalue (icalparameter *param)
| Returns the X-value of param. More...
int | icalparameter_has_same_name (icalparameter *param1, icalparameter *param2)
| Determines if two parameters have the same name. More...
icalparameter_kind | icalparameter_isa (icalparameter *parameter)
int | icalparameter_isa_parameter (void *param)
int | icalparameter_kind_is_valid (const icalparameter_kind kind)
| Checks the validity of a ::icalparameter_kind. More...
const char * | icalparameter_kind_to_string (icalparameter_kind kind)
| Returns a string representing the given ::icalparameter_kind. More...
icalparameter * | icalparameter_new (icalparameter_kind kind)
| Creates new ::icalparameter object. More...
icalparameter * | icalparameter_new_clone (icalparameter *p)
| Creates new ::icalparameter as a clone of the given one. More...
icalparameter * | icalparameter_new_from_string (const char *value)
| Creates new ::icalparameter object from string. More...
icalparameter * | icalparameter_new_from_value_string (icalparameter_kind kind, const char *value)
| Creates new ::icalparameter of a given kind with a given value. 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_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...
icalparameter_kind | icalparameter_string_to_kind (const char *string)
| Returns the ::icalparameter_kind for a given string. More...

## 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_new_from_string
icalparameter * icalparameter_new_from_string(const char *value)
Creates new ::icalparameter object from string.
Definition: icalparameter.c:119
icalparameter_free
void icalparameter_free(icalparameter *parameter)
Frees an ::icalparameter object.
Definition: icalparameter.c:60
icalparameter_as_ical_string
char * icalparameter_as_ical_string(icalparameter *parameter)
Converts ::icalparameter into a string representation.
Definition: icalparameter.c:168

## ◆ icalparameter_as_ical_string_r()

char * icalparameter_as_ical_string_r | ( | icalparameter * | parameter | ) |

Converts ::icalparameter into an 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 `free()`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);
free(str);
}
icalparameter_free(param);

## ◆ 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_clone(), icalparameter_new_from_string() and icalparameter_new_from_value_string(), when they 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_new
icalparameter * icalparameter_new(icalparameter_kind kind)
Creates new ::icalparameter object.
Definition: icalparameter.c:53

## ◆ 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_set_iana_name
void icalparameter_set_iana_name(icalparameter *param, const char *v)
Sets the IANA name of param to v.
Definition: icalparameter.c:400
icalparameter_get_iana_name
const char * icalparameter_get_iana_name(icalparameter *param)
Returns the IANA name of param.
Definition: icalparameter.c:405

## ◆ 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_iana_value
const char * icalparameter_get_iana_value(icalparameter *param)
Returns the IANA value of param.
Definition: icalparameter.c:395
icalparameter_set_iana_value
void icalparameter_set_iana_value(icalparameter *param, const char *v)
Sets the IANA value of param to v.
Definition: icalparameter.c:390

## ◆ 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_xname
const char * icalparameter_get_xname(icalparameter *param)
Returns the X-name of param.
Definition: icalparameter.c:360
icalparameter_set_xname
void icalparameter_set_xname(icalparameter *param, const char *v)
Sets the X-name of param to v.
Definition: icalparameter.c:344

## ◆ 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_get_xvalue
const char * icalparameter_get_xvalue(icalparameter *param)
Returns the X-value of param.
Definition: icalparameter.c:383
icalparameter_set_xvalue
void icalparameter_set_xvalue(icalparameter *param, const char *v)
Sets the X-value of param to v.
Definition: icalparameter.c:367

## ◆ icalparameter_has_same_name()

int 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
  1 if they have the same name, 0 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_has_same_name
int icalparameter_has_same_name(icalparameter *param1, icalparameter *param2)
Determines if two parameters have the same name.
Definition: icalparameter.c:424

## ◆ 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
icalparameter_kind icalparameter_isa(icalparameter *parameter)
Definition: icalparameter.c:320

## ◆ icalparameter_isa_parameter()

int icalparameter_isa_parameter | ( | void * | param | ) |

Determines if the given param is an icalparameter

Parameters

  param | The libical-originated object to check

Returns
  1 if the object is an icalparameter, 0 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_isa_parameter
int icalparameter_isa_parameter(void *param)
Definition: icalparameter.c:329

## ◆ icalparameter_kind_is_valid()

int icalparameter_kind_is_valid | ( | const icalparameter_kind | kind | ) |

Checks the validity of a ::icalparameter_kind.

Parameters

  kind | The icalparameter_kind

Returns
  1 if kind is valid, 0 otherwise

### Usage

assert(icalparameter_kind_is_valid(ICAL_ROLE_PARAMETER));
icalparameter_kind_is_valid
int icalparameter_kind_is_valid(const icalparameter_kind kind)
Checks the validity of a ::icalparameter_kind.

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_kind_to_string
const char * icalparameter_kind_to_string(icalparameter_kind kind)
Returns a string representing the given ::icalparameter_kind.

## ◆ 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_clone()

icalparameter * icalparameter_new_clone | ( | 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_new_clone(param);
if(clone) {
// use clone ...
}
// release parameters
icalparameter_free(param);
icalparameter_free(clone);

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

## ◆ 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 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 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);
icalparameter_string_to_kind
icalparameter_kind icalparameter_string_to_kind(const char *string)
Returns the ::icalparameter_kind for a given string.