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.
typedef void(*	icalattach_free_fn_t) (char *data, void *user_data)
	Function to be called to free the data of an icalattach object.

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

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_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_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);