aboutsummaryrefslogtreecommitdiff
path: root/man/dbfp_init.pod
blob: d94832f0ea9c09e8815ef5e4dcd82f989612615c (plain)
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
=head1 NAME

dbfp_init - initialize the metadata for queries to the DB timetable API

=head1 SYNOPSIS

    #include <dbfp.h>

    int dbfp_init(struct dbfp *dbfp, char *key);

=head1 DESCRIPTION

B<dbfp_init> initializes a I<dbfp> structure that stores the metadata for
queries to the DB timetable API.  I<key> is the API key to use for the
connections.  I<dbfp> must already be allocated.  I<dbfp> and I<key> must not
be NULL.  I<key> is copied to the structure, so it can be changed or freed
after calling this function.

B<dbfp> is a structure defined as:

    struct dbfp {
            char *key;
            CURL *curl;
    };

The user does not have to deal with the fields of this structure.

I<dbfp> structures initialized with this method should be closed by calling
B<dbfp_close>.

=head1 RETURN VALUE

B<dbfp_init> 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> or I<key> is NULL

=item ENOMEM

if there is not enoguh memory to copy I<key> to I<dbfp>

=item DBFP_ERROR_CURL

if curl could not be initialized

=back

=head1 EXAMPLE

    #include <dbfp.h>
    #include <stdio.h>
    #include <stdlib.h>
    #include <string.h>
    
    int main(int argc, char **argv)
    {
            struct dbfp dbfp;
	    int err;
    
            err = dbfp_init(&dbfp, "API key");
            if (!err)
                    printf("DBFP structure created.\n");
            else
                    printf("Could not create DBFP: %s\n", strerror(err));
            dbfp_close(&dbfp);
            
            return err ? EXIT_FAILURE : EXIT_SUCCESS;
    }

=head1 SEE ALSO

L<dbfp_close(3)>, L<dbfp_query_departure(3)>, L<dbfp_query_location(3)>