icalattach.h File Reference

Defines the data structure for iCalendar 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)

Functions
unsigned char *	icalattach_get_data (icalattach *attach)
	Returns the data of the icalattach object. More...
bool	icalattach_get_is_url (const 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

Defines the data structure for iCalendar 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.

Definition in file icalattach.h.

Typedef Documentation

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.

Definition at line 36 of file icalattach.h.

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

Definition at line 46 of file icalattach.h.

Function Documentation

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.

Definition at line 130 of file icalattach.c.

bool icalattach_get_is_url

(

const icalattach *

attach

)

Determines if attach is an URL.

Parameters

attach

the icalattach object to check

See also

icalattach_get_url()

Errors if attach is NULL.

Usage

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

• ```

Returns

true if the specified icalattach is a URL; false otherwise.

Definition at line 115 of file icalattach.c.

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

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

• ```

Definition at line 122 of file icalattach.c.

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.

Definition at line 56 of file icalattach.c.

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

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

• ```

Definition at line 25 of file icalattach.c.

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.

Definition at line 87 of file icalattach.c.

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

• ```c // creates new icalattach *attach = icalattach_new_from_url("http://example.com");

  // release it icalattach_unref(attach);

• ```

Definition at line 95 of file icalattach.c.