=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)>