Libical API Documentation 3.0

Typedefs | Enumerations | Functions
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_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. More...
icalcomponent * | icalparser_clean (icalparser *parser)
| Cleans out an icalparser and returns whatever it has parsed so far. More...
void | icalparser_free (icalparser *parser)
| Frees an icalparser object. More...
char * | icalparser_get_line (icalparser *parser, icalparser_line_gen_func line_gen_func)
| Given a line generator function, returns a single iCal content line. More...
icalparser_state | icalparser_get_state (icalparser *parser)
| Returns current state of the icalparser. More...
icalparser * | icalparser_new (void)
| Creates a new icalparser. More...
icalcomponent * | icalparser_parse (icalparser *parser, icalparser_line_gen_func line_gen_func)
| Message oriented parsing. More...
icalcomponent * | icalparser_parse_string (const char *str)
| Parses a string and returns the parsed ::icalcomponent. More...
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'. More...
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_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_free
void icalparser_free(icalparser *parser)
Frees an icalparser object.
Definition: icalparser.c:121
icalparser_new
icalparser * icalparser_new(void)
Creates a new icalparser.
Definition: icalparser.c:99
icalparser_add_line
icalcomponent * icalparser_add_line(icalparser *parser, char *str)
Adds a single line to be parsed by the icalparser.
Definition: icalparser.c:685
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'.
Definition: icalparser.c:138
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.
Definition: icalparser.c:476
icalcomponent_impl
Definition: icalcomponent.c:36
icalparser_impl
Definition: icalparser.c:51

## ◆ 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_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_get_state
icalparser_state icalparser_get_state(icalparser *parser)
Returns current state of the icalparser.
Definition: icalparser.c:1237
ICALPARSER_ERROR
@ ICALPARSER_ERROR
Definition: icalparser.h:58

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
icalcomponent * icalparser_parse(icalparser *parser, icalparser_line_gen_func line_gen_func)
Message oriented parsing.
Definition: icalparser.c:625

## ◆ 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);
icalerrno
#define icalerrno
Access the current icalerrno value.
Definition: icalerror.h:144
icalparser_parse_string
icalcomponent * icalparser_parse_string(const char *str)
Parses a string and returns the parsed ::icalcomponent.
Definition: icalparser.c:1335

## ◆ 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.