diff options
Diffstat (limited to 'man/dbfp_query_departure.pod')
-rw-r--r-- | man/dbfp_query_departure.pod | 134 |
1 files changed, 134 insertions, 0 deletions
diff --git a/man/dbfp_query_departure.pod b/man/dbfp_query_departure.pod new file mode 100644 index 0000000..0fcae28 --- /dev/null +++ b/man/dbfp_query_departure.pod @@ -0,0 +1,134 @@ +=head1 NAME + +dbfp_query_departure - get a list of departures at a given station from the +DB timetable API + +=head1 SYNOPSIS + + #include <dbfp.h> + + int dbfp_query_departure(struct dbfp *dbfp, char *location_id, time_t time, + size_t *n, struct dbfp_departure **departures); + +=head1 DESCRIPTION + +B<dbfp_query_departure> queries a list of departures at a the station with the +given I<location_id> at the given I<time> using the connection metadata stored +in I<dbfp>. The number of results is stored in I<n>. The results are stored +in I<departures>. The memory for the I<departures> is allocated by the +function. The stored array contains exactly I<n> elements, and is not NULL +terminated. + +Possible values for I<location_id> can be retrieved using +I<dbfp_query_location>. If I<time> is zero, the current time is used. +I<dbfp>, I<location_id>, I<n> and I<departures> must not be NULL. I<dbfp> must +have been initialized with I<dbfp_init>. The elements in I<departures> should +be closed with I<dbfp_departure_close>. I<departures> should be freed by the +caller. + +If the query fails, the values of I<n> and I<departures> are set to 0 and NULL +respectively. + +The B<dbfp_departure> structure is defined as: + + struct dbfp_departure { + char *name; + char *type; + char *stopid; + char *stop; + time_t time; + char *direction; + char *track; + }; + +I<name> is the name of the departing train, I<type> is the type of the train. +I<stopid> is the ID of the stop the train departs from, and I<stop> is its +name. I<time> is the departure time, I<direction> the direction of the train, +and I<track> the departure track. + +=head1 RETURN VALUE + +B<dbfp_query_departure> returns zero if successful, or a non-zero error code. +Positive error codes are from I<errno.h>, negative error codes are specific +to dbfp. + +=head1 ERRORS + +=over + +=item EINVAL + +if I<dbfp>, I<location_id>, I<n> or I<departures> is NULL + +=item ENOMEM + +if there is not enough memory to store the results of the query + +=item DBFP_ERROR_CURL + +if an error occured during the preparation or execution of the network request + +=item DBFP_ERROR_FORMAT + +if an error occurs during the formatting of the URL + +=item DBFP_ERROR_PARSE + +if an error occurs during the parsing of the XML response + +=item DBFP_ERROR_STRUCTURE + +if the API response has not the expected structure + +=back + +=head1 BUGS + +Due to a typo in the DB timetable API, the I<type> field of one or more of the +I<departures> elements might be NULL. + +The time zone handling has to be checked and documented. + +=head1 EXAMPLE + + #include <dbfp.h> + #include <stdio.h> + #include <stdlib.h> + #include <string.h> + + int main(int argc, char **argv) + { + int err = 0; + struct dbfp dbfp; + struct dbfp_departure *departures = NULL; + size_t n = 0; + size_t i; + + err = dbfp_init(&dbfp, "API key"); + if (err) + goto cleanup; + err = dbfp_query_departure(&dbfp, "8000105", 0, &n, &departures); + if (err) + goto cleanup; + + printf("Number of matches: %zu\n", n); + if (n > 0) + printf("Departures from %s:\n", departures[0].stop); + for (i = 0; i < n; i++) + printf("%s to %s from track %s\n", departures[i].name, + departures[i].direction, departures[i].track); + + cleanup: + if (err) + printf("An error occured: %s\n", strerror(err)); + for (i = 0; i < n; i++) + dbfp_departure_close(&departures[i]); + free(departures); + dbfp_close(&dbfp); + + return err ? EXIT_FAILURE : EXIT_SUCCESS; + } + +=head1 SEE ALSO + +L<dbfp_init(3)>, L<dbfp_departure_close(3)> |