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
|
=head1 NAME
dbfp_query_loation - get a list of stations matching a string from the DB
timetable API
=head1 SYNOPSIS
#include <dbfp.h>
int dbfp_query_location(struct dbfp *dbfp, char *input, size_t *n,
struct dbfp_location **locations);
=head1 DESCRIPTION
B<dbfp_query_location> queries a list of locations matching the query string
I<input> from the DB timetable API using the connection metadata stored in
I<dbfp>. The number of results is stored in I<n>. The results are stored in
I<locations>. The memory for the I<locations> is allocated by the function.
The stored array contains exactly I<n> elements, and is not NULL terminated.
I<dbfp>, I<input>, I<n> and I<locations> must not be NULL. I<dbfp> must have
been initialized with I<dbfp_init>. The elements in I<locations> should be
closed with I<dbfp_location_close>. I<locations> should be freed by the
caller.
If the query fails, the values of I<n> and I<locations> are set to 0 and NULL
respectively.
The B<dbfp_location> structure is defined as:
struct dbfp_location {
char *name;
char *id;
float lon;
float lat;
};
I<name> is the name of the station. I<id> is the DB id of the station. It
seems to be an integer, but this is not guaranteed. I<lon> and I<lat> are the
coordinates of the station.
=head1 RETURN VALUE
B<dbfp_query_location> 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<input>, I<n> or I<locations> 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 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_location *locations = NULL;
size_t n = 0;
size_t i;
err = dbfp_init(&dbfp, "API key");
if (err)
goto cleanup;
err = dbfp_query_location(&dbfp, "Freibu", &n, &locations);
if (err)
goto cleanup;
printf("Number of matches: %zu\n", n);
for (i = 0; i < n; i++)
printf("%s: %s (%.2f, %.2f)", locations[i].id,
locations[i].name, locations[i].lon,
locations[i].lat);
cleanup:
if (err)
printf("An error occured: %s\n", strerror(err));
for (i = 0; i < n; i++)
dbfp_location_close(&locations[i]);
free(locations);
dbfp_close(&dbfp);
return err ? EXIT_FAILURE : EXIT_SUCCESS;
}
=head1 SEE ALSO
L<dbfp_init(3)>, L<dbfp_location_close(3)>
|
