$darkmode
Libical API Documentation 4.0 STABLE VERSION Visit the v3.0 documentation
Functions
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. More...
 
char * vcardparameter_as_vcard_string_r (vcardparameter *parameter)
 Converts vcardparameter into an string representation according to RFC5445/RFC6868. More...
 
vcardparameter * vcardparameter_clone (const vcardparameter *old)
 Creates new vcardparameter as a clone of the given one. More...
 
void vcardparameter_free (vcardparameter *parameter)
 Frees an vcardparameter object. More...
 
const char * vcardparameter_get_iana_name (const vcardparameter *param)
 Returns the IANA name of param. More...
 
const char * vcardparameter_get_iana_value (const vcardparameter *param)
 Returns the IANA value of param. More...
 
const char * vcardparameter_get_xname (const vcardparameter *param)
 Returns the X-name of param. More...
 
const char * vcardparameter_get_xvalue (const vcardparameter *param)
 Returns the X-value of param. More...
 
bool vcardparameter_has_same_name (const vcardparameter *param1, const vcardparameter *param2)
 Determines if two parameters have the same name. More...
 
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. More...
 
const char * vcardparameter_kind_to_string (vcardparameter_kind kind)
 Returns a string representing the given vcardparameter_kind. More...
 
vcardvalue_kind vcardparameter_kind_value_kind (const vcardparameter_kind kind, int *is_multivalued)
 
vcardparameter * vcardparameter_new (vcardparameter_kind kind)
 Creates new vcardparameter object. More...
 
vcardparameter * vcardparameter_new_from_string (const char *str)
 Creates new vcardparameter object from string. More...
 
vcardparameter * vcardparameter_new_from_value_string (vcardparameter_kind kind, const char *value)
 Creates new vcardparameter of a given kind with a given value. More...
 
void vcardparameter_set_iana_name (vcardparameter *param, const char *v)
 Sets the IANA name of param to v. More...
 
void vcardparameter_set_iana_value (vcardparameter *param, const char *v)
 Sets the IANA value of param to v. More...
 
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. More...
 
void vcardparameter_set_xvalue (vcardparameter *param, const char *v)
 Sets the X-value of param to v. More...
 
vcardparameter_kind vcardparameter_string_to_kind (const char *string)
 Returns the vcardparameter_kind for a given string. More...
 

Detailed Description

Defines the data structure representing vCard parameters.

Definition in file vcardparameter.h.

Function Documentation

char* vcardparameter_as_vcard_string ( vcardparameter *  parameter)

Converts vcardparameter into a string representation.

Parameters
parameterThe 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

  • ```c vcardparameter *param = vcardparameter_new_from_string("ROLE=CHAIR");

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

    vcardparameter_free(param);

  • ```

Definition at line 173 of file vcardparameter.c.

char* vcardparameter_as_vcard_string_r ( vcardparameter *  parameter)

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

Parameters
parameterThe 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

  • ```c 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 191 of file vcardparameter.c.

vcardparameter* vcardparameter_clone ( const vcardparameter *  old)

Creates new vcardparameter as a clone of the given one.

Parameters
oldThe 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

  • ```x // 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 80 of file vcardparameter.c.

void vcardparameter_free ( vcardparameter *  parameter)

Frees an vcardparameter object.

Parameters
parameterThe 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

  • ```c vcardparameter *param = vcardparameter_new();

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

    // after use, release it vcardparameter_free(param);

  • ```

Definition at line 51 of file vcardparameter.c.

const char* vcardparameter_get_iana_name ( const vcardparameter *  param)

Returns the IANA name of param.

Parameters
paramThe 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

  • ```c // 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 373 of file vcardparameter.c.

const char* vcardparameter_get_iana_value ( const vcardparameter *  param)

Returns the IANA value of param.

Parameters
paramThe 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

  • ```c // 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.

const char* vcardparameter_get_xname ( const vcardparameter *  param)

Returns the X-name of param.

Parameters
paramThe 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

  • ```c // 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 328 of file vcardparameter.c.

const char* vcardparameter_get_xvalue ( const vcardparameter *  param)

Returns the X-value of param.

Parameters
paramThe 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

  • ```c // 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 351 of file vcardparameter.c.

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

Determines if two parameters have the same name.

Parameters
param1First parameter to compare
param2Second 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

  • ```c // 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 392 of file vcardparameter.c.

vcardparameter_kind vcardparameter_isa ( const vcardparameter *  parameter)

Returns the vcardparameter_kind of parameter.

Parameters
parameterThe vcardparameter whose kind to determine
Returns
The vcardparameter_kind of the parameter

Error handling Returns ICAL_NO_PARAMETER when passed NULL.

Usage

1 // create parameter
2 vcardparameter *param = vcardparameter_new_from_string("ROLE=CHAIR");
3 
4 // check what type of parameter this is
5 assert(vcardparameter_isa(param) == ICAL_ROLE_PARAMETER);
6 
7 // release memory
8 vcardparameter_free(param);

Definition at line 292 of file vcardparameter.c.

bool vcardparameter_isa_parameter ( void *  param)

Determines if the given param is an vcardparameter

Parameters
paramThe 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

  • ```c // 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 301 of file vcardparameter.c.

bool vcardparameter_kind_is_valid ( const vcardparameter_kind  kind)

Checks the validity of a vcardparameter_kind.

Parameters
kindThe vcardparameter_kind
Returns
true if kind is valid, false otherwise
Usage
  • ```c assert(vcardparameter_kind_is_valid(ICAL_ROLE_PARAMETER));
  • ```
Since
3.0.4
const char* vcardparameter_kind_to_string ( vcardparameter_kind  kind)

Returns a string representing the given vcardparameter_kind.

Parameters
kindThe 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
  • ```c 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* vcardparameter_new ( vcardparameter_kind  kind)

Creates new vcardparameter object.

Parameters
kindThe 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

  • ```c // create new parameter vcardparameter *parameter = vcardparameter_new();

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

    // release parameter vcardparameter_free(parameter);

  • ```

Definition at line 44 of file vcardparameter.c.

vcardparameter* vcardparameter_new_from_string ( const char *  str)

Creates new vcardparameter object from string.

Parameters
strThe 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

  • ```c vcardparameter *param = vcardparameter_new_from_string("ROLE=CHAIR");

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

    vcardparameter_free(param);

  • ```

Definition at line 124 of file vcardparameter.c.

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

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

Parameters
kindThe kind of vcardparameter to create
valueThe 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

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

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

Sets the IANA name of param to v.

Parameters
paramThe vcardparameter to change
vThe 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

  • ```c // 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 368 of file vcardparameter.c.

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

Sets the IANA value of param to v.

Parameters
paramThe vcardparameter to change
vThe 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

  • ```c // 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 358 of file vcardparameter.c.

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

Sets the X-name of param to v.

Parameters
paramThe vcardparameter to change
vThe 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

  • ```c // 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 312 of file vcardparameter.c.

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

Sets the X-value of param to v.

Parameters
paramThe vcardparameter to change
vThe 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

  • ```c // 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 335 of file vcardparameter.c.

vcardparameter_kind vcardparameter_string_to_kind ( const char *  string)

Returns the vcardparameter_kind for a given string.

Parameters
stringA 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
  • ```c 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);
  • ```
Generated by   doxygen 1.8.10