Libical API Documentation 3.0

Typedefs | Functions
icalattach.h File Reference

A set of functions to handle iCal attachments. More...

Go to the source code of this file.

## Typedefs
typedef struct icalattach_impl | icalattach
| An iCal attach object representing a link to a document object. More...
typedef void(* | icalattach_free_fn_t) (char *data, void *user_data)
| Function to be called to free the data of an icalattach object. More...

## Functions
unsigned char * | icalattach_get_data (icalattach *attach)
| Returns the data of the icalattach object. More...
int | icalattach_get_is_url (icalattach *attach)
| Determines if attach is an URL. More...
const char * | icalattach_get_url (icalattach *attach)
| Returns the URL of the icalattach object. More...
icalattach * | icalattach_new_from_data (const char *data, icalattach_free_fn_t free_fn, void *free_fn_data)
| Creates new icalattach object from data. More...
icalattach * | icalattach_new_from_url (const char *url)
| Creates new icalattach object from a URL. More...
void | icalattach_ref (icalattach *attach)
| Increments reference count of the icalattach. More...
void | icalattach_unref (icalattach *attach)
| Decrements reference count of the icalattach. More...

## Detailed Description

A set of functions to handle iCal attachments.

With the `ATTACH` property, the iCal standard defines a way to associate a document object with a calendar component.

These are represented with icalattach objects in libical. This file contains functions to create and work with these objects.

## Typedef Documentation

## ◆ icalattach

icalattach

An iCal attach object representing a link to a document object.

Represents an association with a document object. icalattach objects are reference counted, meaning that if the last reference to them is removed (with icalattach_unref()), they are destroyed.

## ◆ icalattach_free_fn_t

icalattach_free_fn_t

Function to be called to free the data of an icalattach object.

Warning
  Currently not used

This function type is used to free the data from an icalattach object created with icalattach_new_from_data(). It is currently not used

## Function Documentation

## ◆ icalattach_get_data()

unsigned char * icalattach_get_data | ( | icalattach * | attach | ) |

Returns the data of the icalattach object.

Parameters

  attach | The object from which to return the data

Returns
  The data of the object

See also
  icalattach_get_is_url()

Returns the URL of the icalattach object.

Error handling
  Returns `NULL` and set icalerrno to ICAL_BADARG_ERROR if attach is `NULL`. Undefined behaviour if the object is a URL (check with icalattach_get_is_url()).

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

## ◆ icalattach_get_is_url()

int icalattach_get_is_url | ( | icalattach * | attach | ) |

Determines if attach is an URL.

Parameters

  attach | the icalattach object to check

Returns
  1 if it is a URL, otherwise 0.

See also
  icalattach_get_url()

Error handling
  Returns `NULL` and sets icalerrno to ICAL_BADARG_ERROR if attach is `NULL`.

### Usage

// creates new
icalattach *attach = icalattach_new_from_url("http://example.com");
// checks if it is a URL
assert(icalattach_get_is_url(attach));
// release it
icalattach_unref(attach);
icalattach_unref
void icalattach_unref(icalattach *attach)
Decrements reference count of the icalattach.
Definition: icalattach.c:99
icalattach_get_is_url
int icalattach_get_is_url(icalattach *attach)
Determines if attach is an URL.
Definition: icalattach.c:118
icalattach_new_from_url
icalattach * icalattach_new_from_url(const char *url)
Creates new icalattach object from a URL.
Definition: icalattach.c:29
icalattach_impl
Definition: icalattachimpl.h:26

## ◆ icalattach_get_url()

const char * icalattach_get_url | ( | icalattach * | attach | ) |

Returns the URL of the icalattach object.

Parameters

  attach | The object from which to return the URL

Returns
  The URL of the object

See also
  icalattach_get_is_url()

Returns the URL of the icalattach object.

Error handling
  Returns `NULL` and set icalerrno to ICAL_BADARG_ERROR if attach is `NULL`. Undefined behaviour if the object is not a URL (check with icalattach_get_is_url()).

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

# Usage

// creates new
icalattach *attach = icalattach_new_from_url("http://example.com");
// checks it
assert(icalattach_get_is_url(attach));
assert(0 == strcmp(icalattach_get_url(attach), "http://example.com"));
// release it
icalattach_unref(attach);
icalattach_get_url
const char * icalattach_get_url(icalattach *attach)
Returns the URL of the icalattach object.
Definition: icalattach.c:125

## ◆ icalattach_new_from_data()

icalattach * icalattach_new_from_data | ( | const char * | data,
|  | icalattach_free_fn_t | free_fn,
|  | void * | free_fn_data
| ) |  |

Creates new icalattach object from data.

Parameters

  data | The data to create the icalattach from
  free_fn | The function to free the data
  free_fn_data | Data to pass to the free_fn

Returns
  An icalattach object with the given data

See also
  icalattach_unref()

Error handling
  If url is `NULL`, it returns `NULL` and sets icalerrno to ICAL_BADARG_ERROR. If there was an error allocating memory, it returns `NULL` and sets `errno` to `ENOMEM`.

Ownership
  The returned icalattach object is owned by the caller of the function. icalattach objects are reference counted, which means that after use, icalattach_unref() needs to be called to signal that they are not used anymore.

## ◆ icalattach_new_from_url()

icalattach * icalattach_new_from_url | ( | const char * | url | ) |

Creates new icalattach object from a URL.

Parameters

  url | The URL to create the object from

Returns
  An icalattach object with the given URL as association

See also
  icalattach_unref()

Error handling
  If url is `NULL`, it returns `NULL` and sets icalerrno to ICAL_BADARG_ERROR. If there was an error allocating memory, it returns `NULL` and sets `errno` to `ENOMEM`.

Ownership
  The returned icalattach object is owned by the caller of the function. icalattach objects are reference counted, which means that after use, icalattach_unref() needs to be called to signal that they are not used anymore.

### Usage

// creates new
icalattach *attach = icalattach_new_from_url("http://example.com");
// checks it
assert(icalattach_get_is_url(attach));
assert(0 == strcmp(icalattach_get_url(attach), "http://example.com"));
// release it
icalattach_unref(attach);

## ◆ icalattach_ref()

void icalattach_ref | ( | icalattach * | attach | ) |

Increments reference count of the icalattach.

Parameters

  attach | The object to increase the reference count of

See also
  icalattach_unref()

Error handling
  If attach is `NULL`, or the reference count is smaller than 0, it sets icalerrno to ICAL_BADARG_ERROR.

Ownership
  By increasing the refcount of attach, you are signaling that you are using it, and it is the owner's responsibility to call icalattach_unref() after it's no longer used.

## ◆ icalattach_unref()

void icalattach_unref | ( | icalattach * | attach | ) |

Decrements reference count of the icalattach.

Parameters

  attach | The object to decrease the reference count of

See also
  icalattach_ref()

Decreases the reference count of attach. If this was the last user of the object, it is freed.

Error handling
  If attach is `NULL`, or the reference count is smaller than 0, it sets icalerrno to ICAL_BADARG_ERROR.

Ownership
  Calling this function releases the icalattach back to the library, and it must not be used afterwards.

### Usage

// creates new
icalattach *attach = icalattach_new_from_url("http://example.com");
// release it
icalattach_unref(attach);