1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
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)>
|
