icalparser.h File Reference

Line-oriented parsing. More...

Go to the source code of this file.

Typedefs
typedef struct icalparser_impl	icalparser
typedef char *(*	icalparser_line_gen_func) (char *s, size_t size, void *d)
typedef enum icalparser_state	icalparser_state

Enumerations
enum	icalparser_ctrl { ICALPARSER_CTRL_KEEP , ICALPARSER_CTRL_OMIT , ICALPARSER_CTRL_ERROR }
	Defines how to handle invalid CONTROL characters in content lines. More...
enum	icalparser_state {   ICALPARSER_ERROR , ICALPARSER_SUCCESS , ICALPARSER_BEGIN_COMP , ICALPARSER_END_COMP ,   ICALPARSER_IN_PROGRESS }
	Represents the current state of the parser. More...

Functions
icalcomponent *	icalparser_add_line (icalparser *parser, char *str)
	Adds a single line to be parsed by the icalparser.
icalcomponent *	icalparser_clean (icalparser *parser)
	Cleans out an icalparser and returns whatever it has parsed so far.
void	icalparser_free (icalparser *parser)
	Frees an icalparser object.
enum icalparser_ctrl	icalparser_get_ctrl (void)
	Get the current parser setting how to handle CONTROL characters.
char *	icalparser_get_line (icalparser *parser, icalparser_line_gen_func line_gen_func)
	Given a line generator function, returns a single iCal content line.
icalparser_state	icalparser_get_state (icalparser *parser)
	Returns current state of the icalparser.
icalparser *	icalparser_new (void)
	Creates a new icalparser.
icalcomponent *	icalparser_parse (icalparser *parser, icalparser_line_gen_func line_gen_func)
	Message oriented parsing.
icalcomponent *	icalparser_parse_string (const char *str)
	Parses a string and returns the parsed icalcomponent.
void	icalparser_set_ctrl (enum icalparser_ctrl ctrl)
	Set the parser setting how to handle CONTROL characters.
void	icalparser_set_gen_data (icalparser *parser, void *data)
	Sets the data that icalparser_parse will give to the line_gen_func as the parameter 'd'.
char *	icalparser_string_line_generator (char *out, size_t buf_size, void *d)

Detailed Description

Line-oriented parsing.

This file provides methods to parse iCalendar-formatted data into the structures provided by this library.

Usage

Create a new parser via icalparser_new_parser(), then add lines one at a time with icalparser_add_line(). icalparser_add_line() will return non-zero when it has finished with a component.

Typedef Documentation

icalparser

icalparser

Implementation of the icalparser struct, which holds the state for the current parsing operation.

Enumeration Type Documentation

icalparser_ctrl

enum icalparser_ctrl

Defines how to handle invalid CONTROL characters in content lines.

Enumerator
ICALPARSER_CTRL_KEEP	Keep CONTROL characters in content-line
ICALPARSER_CTRL_OMIT	Omit CONTROL characters from content-line
ICALPARSER_CTRL_ERROR	Insert a X-LIC-ERROR instead of content-line

icalparser_state

enum icalparser_state

Represents the current state of the parser.

Enumerator
ICALPARSER_ERROR	An error occurred while parsing.
ICALPARSER_SUCCESS	Parsing was successful.
ICALPARSER_BEGIN_COMP	Currently parsing the begin of a component.
ICALPARSER_END_COMP	Currently parsing the end of the component.
ICALPARSER_IN_PROGRESS	Parsing is currently in progress.

Function Documentation

icalparser_add_line()

icalcomponent * icalparser_add_line	(	icalparser *	parser,
		char *	str
	)

Adds a single line to be parsed by the icalparser.

Parameters

parser	The parser to use
str	A string representing a single line of RFC5545-formatted iCalendar data

Returns

When this was the last line of the component to be parsed, it returns the icalcomponent, otherwise it returns NULL.

See also

icalparser_parse()

Error handling

• If parser is NULL, it returns NULL and sets icalerrno to ICAL_BADARG_ERROR.
• If line is empty, if returns NULL
• If line is NULL, it returns NULL and sets the parser's icalparser_state to ICALPARSER_ERROR.
• For errors during parsing, the functions can set the icalparser_state to ICALPARSER_ERROR and/or return components of the type ICAL_XLICINVALID_COMPONENT, or components with properties of the type ICAL_XLICERROR_PROPERTY.

Ownership

Ownership of the str is transferred to libical upon calling this method. The returned icalcomponent is owned by the caller and needs to be free()d with the appropriate method after it's no longer needed.

Example

char* read_stream(char *s, size_t size, void *d)
{
    return fgets(s, (int)size, (FILE*)d);
}
 
void parse()
{
    char* line;
    FILE* stream;
    icalcomponent *component;
 
    icalparser *parser = icalparser_new();
    stream = fopen(argv[1],"r");
 
    icalparser_set_gen_data(parser, stream);
 
    do{
        // get a single content line
        line = icalparser_get_line(parser, read_stream);
 
        // add that line to the parser
        c = icalparser_add_line(parser,line);
 
        // once we parsed a component, print it
        if (c != 0) {
            printf("%s", icalcomponent_as_ical_string(c));
            icalcomponent_free(c);
        }
    } while (line != 0);
 
    icalparser_free(parser);
}

icalparser_clean()

icalcomponent * icalparser_clean

(

icalparser *

parser

)

Cleans out an icalparser and returns whatever it has parsed so far.

Parameters

parser

The icalparser to clean

Returns

The parsed icalcomponent

Error handling

If parser is NULL, it returns NULL and sets icalerrno to ICAL_BADARG_ERROR. For parsing errors, it inserts an X-LIC-ERROR property into the affected components.

Ownership

The returned icalcomponent is property of the caller and needs to be free'd with icalcomponent_free() after use.

This will parse components even if it hasn't encountered a proper END tag for it yet and return them, as well as clearing any intermediate state resulting from being in the middle of parsing something so the parser can be used to parse something new.

icalparser_free()

void icalparser_free

(

icalparser *

parser

)

Frees an icalparser object.

Parameters

parser

The icalparser to be freed.

Example

icalparser *parser = icalparser_new();
 
// use parser ...
 
icalparser_free(parser);

icalparser_get_ctrl()

enum icalparser_ctrl icalparser_get_ctrl

(

void

)

Get the current parser setting how to handle CONTROL characters.

Returns

The current parser setting

icalparser_get_line()

char * icalparser_get_line	(	icalparser *	parser,
		icalparser_line_gen_func	line_gen_func
	)

Given a line generator function, returns a single iCal content line.

Returns

A pointer to a single line of data or NULL if it reached end of file reading from the line_gen_func. Note that the pointer returned is owned by libical and must not be free()d by the user.

Parameters

parser	The parser object to use
line_gen_func	The function to use for reading data

This function uses the supplied line_gen_func to read data in, until it has read a full line, and returns the full line. It includes any continuation lines, which start with a space after a newline. To supply arbitrary data (as the parameter d) to your line_gen_func, call icalparser_set_gen_data().

icalparser_get_state()

icalparser_state icalparser_get_state

(

icalparser *

parser

)

Returns current state of the icalparser.

Parameters

parser

The (valid, non-NULL) parser object

Returns

The current state of the icalparser, as an icalparser_state

Example

icalparser *parser = icalparser_new();
 
// use icalparser...
 
if(icalparser_get_state(parser) == ICALPARSER_ERROR) {
    // handle error
} else {
    // ...
}

icalparser_free(parser);

icalparser_new()

icalparser * icalparser_new

(

void

)

Creates a new icalparser.

Returns

An icalparser object

Error handling

On error, it returns NULL and sets icalerrno to ICAL_NEWFAILED_ERROR.

Ownership

All icalparser objects created with this function need to be freed using the icalparser_free() function.

Usage

// create new parser
icalparser *parser = icalparser_new();
 
// do something with it...
 
// free parser
icalparser_free(parser);

icalparser_parse()

icalcomponent * icalparser_parse	(	icalparser *	parser,
		icalparser_line_gen_func	line_gen_func
	)

Message oriented parsing.

Parameters

parser	The parser to use
line_gen_func	A function that returns one content line per invocation

Returns

The parsed icalcomponent

See also

icalparser_parse_string()

Reads an icalcomponent using the supplied line_gen_func, returning the parsed component (or NULL on error).

Error handling

• If parser is NULL, it returns NULL and sets icalerrno to ICAL_BADARG_ERROR.
• If data read by line_gen_func is empty, if returns NULL
• If data read by line_gen_func is NULL, it returns NULL and sets the parser's icalparser_state to ICALPARSER_ERROR.
• For errors during parsing, the functions can set the icalparser_state to ICALPARSER_ERROR and/or return components of the type ICAL_XLICINVALID_COMPONENT, or components with properties of the type ICAL_XLICERROR_PROPERTY.

Ownership

The returned icalcomponent is owned by the caller of the function, and needs to be free()d with the appropriate method when no longer needed.

Example

char* read_stream(char *s, size_t size, void *d)
{
    return fgets(s, (int)size, (FILE*)d);
}
 
void parse()
{
    char* line;
    FILE* stream;
    icalcomponent *component;
 
    icalparser *parser = icalparser_new();
    stream = fopen(argv[1],"r");
 
    icalparser_set_gen_data(parser, stream);
 
    // use the parse method to parse the input data
    component = icalparser_parse(parser, read_stream);
 
    // once we parsed a component, print it
    printf("%s", icalcomponent_as_ical_string(c));
    icalcomponent_free(c);
 
    icalparser_free(parser);
}

icalparser_parse_string()

icalcomponent * icalparser_parse_string

(

const char *

str

)

Parses a string and returns the parsed icalcomponent.

Parameters

str	The iCal formatted data to be parsed

Returns

An icalcomponent representing the iCalendar

Error handling

On error, returns NULL and sets icalerrno

Ownership

The returned icalcomponent is owned by the caller of the function, and needs to be free'd with the appropriate functions after use.

Example

char *ical_string;
 
// parse ical_string
icalcomponent *component = icalparser_parse_string(ical_string);
 
if(!icalerrno || component == NULL) {
    // use component ...
}
 
// release component
icalcomponent_free(component);

icalparser_set_ctrl()

void icalparser_set_ctrl

(

enum icalparser_ctrl

ctrl

)

Set the parser setting how to handle CONTROL characters.

Parameters

ctrl	The setting to use

icalparser_set_gen_data()

void icalparser_set_gen_data	(	icalparser *	parser,
		void *	data
	)

Sets the data that icalparser_parse will give to the line_gen_func as the parameter 'd'.

Parameters

parser	The icalparser this applies to
data	The pointer which will be passed to the line_gen_func as argument d

If you use any of the icalparser_parser() or icalparser_get_line() functions, the line_gen_func that they expect has a third void *d argument. This function sets what will be passed to your line_gen_function as such argument.