diff options
Diffstat (limited to 'include/git2/transport.h')
| -rw-r--r-- | include/git2/transport.h | 328 |
1 files changed, 328 insertions, 0 deletions
diff --git a/include/git2/transport.h b/include/git2/transport.h new file mode 100644 index 000000000..5e9968363 --- /dev/null +++ b/include/git2/transport.h @@ -0,0 +1,328 @@ +/* + * Copyright (C) the libgit2 contributors. All rights reserved. + * + * This file is part of libgit2, distributed under the GNU GPL v2 with + * a Linking Exception. For full terms see the included COPYING file. + */ +#ifndef INCLUDE_git_transport_h__ +#define INCLUDE_git_transport_h__ + +#include "indexer.h" +#include "net.h" +#include "types.h" + +/** + * @file git2/transport.h + * @brief Git transport interfaces and functions + * @defgroup git_transport interfaces and functions + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +/* + *** Begin interface for credentials acquisition *** + */ + +typedef enum { + /* git_cred_userpass_plaintext */ + GIT_CREDTYPE_USERPASS_PLAINTEXT = 1, +} git_credtype_t; + +/* The base structure for all credential types */ +typedef struct git_cred { + git_credtype_t credtype; + void (*free)( + struct git_cred *cred); +} git_cred; + +/* A plaintext username and password */ +typedef struct git_cred_userpass_plaintext { + git_cred parent; + char *username; + char *password; +} git_cred_userpass_plaintext; + +/** + * Creates a new plain-text username and password credential object. + * The supplied credential parameter will be internally duplicated. + * + * @param out The newly created credential object. + * @param username The username of the credential. + * @param password The password of the credential. + * @return 0 for success or an error code for failure + */ +GIT_EXTERN(int) git_cred_userpass_plaintext_new( + git_cred **out, + const char *username, + const char *password); + +/** + * Signature of a function which acquires a credential object. + * + * @param cred The newly created credential object. + * @param url The resource for which we are demanding a credential. + * @param username_from_url The username that was embedded in a "user@host" + * remote url, or NULL if not included. + * @param allowed_types A bitmask stating which cred types are OK to return. + * @param payload The payload provided when specifying this callback. + * @return 0 for success or an error code for failure + */ +typedef int (*git_cred_acquire_cb)( + git_cred **cred, + const char *url, + const char *username_from_url, + unsigned int allowed_types, + void *payload); + +/* + *** End interface for credentials acquisition *** + *** Begin base transport interface *** + */ + +typedef enum { + GIT_TRANSPORTFLAGS_NONE = 0, + /* If the connection is secured with SSL/TLS, the authenticity + * of the server certificate should not be verified. */ + GIT_TRANSPORTFLAGS_NO_CHECK_CERT = 1 +} git_transport_flags_t; + +typedef void (*git_transport_message_cb)(const char *str, int len, void *data); + +typedef struct git_transport { + unsigned int version; + /* Set progress and error callbacks */ + int (*set_callbacks)(struct git_transport *transport, + git_transport_message_cb progress_cb, + git_transport_message_cb error_cb, + void *payload); + + /* Connect the transport to the remote repository, using the given + * direction. */ + int (*connect)(struct git_transport *transport, + const char *url, + git_cred_acquire_cb cred_acquire_cb, + void *cred_acquire_payload, + int direction, + int flags); + + /* This function may be called after a successful call to connect(). The + * provided callback is invoked for each ref discovered on the remote + * end. */ + int (*ls)(struct git_transport *transport, + git_headlist_cb list_cb, + void *payload); + + /* Executes the push whose context is in the git_push object. */ + int (*push)(struct git_transport *transport, git_push *push); + + /* This function may be called after a successful call to connect(), when + * the direction is FETCH. The function performs a negotiation to calculate + * the wants list for the fetch. */ + int (*negotiate_fetch)(struct git_transport *transport, + git_repository *repo, + const git_remote_head * const *refs, + size_t count); + + /* This function may be called after a successful call to negotiate_fetch(), + * when the direction is FETCH. This function retrieves the pack file for + * the fetch from the remote end. */ + int (*download_pack)(struct git_transport *transport, + git_repository *repo, + git_transfer_progress *stats, + git_transfer_progress_callback progress_cb, + void *progress_payload); + + /* Checks to see if the transport is connected */ + int (*is_connected)(struct git_transport *transport); + + /* Reads the flags value previously passed into connect() */ + int (*read_flags)(struct git_transport *transport, int *flags); + + /* Cancels any outstanding transport operation */ + void (*cancel)(struct git_transport *transport); + + /* This function is the reverse of connect() -- it terminates the + * connection to the remote end. */ + int (*close)(struct git_transport *transport); + + /* Frees/destructs the git_transport object. */ + void (*free)(struct git_transport *transport); +} git_transport; + +#define GIT_TRANSPORT_VERSION 1 +#define GIT_TRANSPORT_INIT {GIT_TRANSPORT_VERSION} + +/** + * Function to use to create a transport from a URL. The transport database + * is scanned to find a transport that implements the scheme of the URI (i.e. + * git:// or http://) and a transport object is returned to the caller. + * + * @param out The newly created transport (out) + * @param owner The git_remote which will own this transport + * @param url The URL to connect to + * @return 0 or an error code + */ +GIT_EXTERN(int) git_transport_new(git_transport **out, git_remote *owner, const char *url); + +/* Signature of a function which creates a transport */ +typedef int (*git_transport_cb)(git_transport **out, git_remote *owner, void *param); + +/* Transports which come with libgit2 (match git_transport_cb). The expected + * value for "param" is listed in-line below. */ + +/** + * Create an instance of the dummy transport. + * + * @param out The newly created transport (out) + * @param owner The git_remote which will own this transport + * @param payload You must pass NULL for this parameter. + * @return 0 or an error code + */ +GIT_EXTERN(int) git_transport_dummy( + git_transport **out, + git_remote *owner, + /* NULL */ void *payload); + +/** + * Create an instance of the local transport. + * + * @param out The newly created transport (out) + * @param owner The git_remote which will own this transport + * @param payload You must pass NULL for this parameter. + * @return 0 or an error code + */ +GIT_EXTERN(int) git_transport_local( + git_transport **out, + git_remote *owner, + /* NULL */ void *payload); + +/** + * Create an instance of the smart transport. + * + * @param out The newly created transport (out) + * @param owner The git_remote which will own this transport + * @param payload A pointer to a git_smart_subtransport_definition + * @return 0 or an error code + */ +GIT_EXTERN(int) git_transport_smart( + git_transport **out, + git_remote *owner, + /* (git_smart_subtransport_definition *) */ void *payload); + +/* + *** End of base transport interface *** + *** Begin interface for subtransports for the smart transport *** + */ + +/* The smart transport knows how to speak the git protocol, but it has no + * knowledge of how to establish a connection between it and another endpoint, + * or how to move data back and forth. For this, a subtransport interface is + * declared, and the smart transport delegates this work to the subtransports. + * Three subtransports are implemented: git, http, and winhttp. (The http and + * winhttp transports each implement both http and https.) */ + +/* Subtransports can either be RPC = 0 (persistent connection) or RPC = 1 + * (request/response). The smart transport handles the differences in its own + * logic. The git subtransport is RPC = 0, while http and winhttp are both + * RPC = 1. */ + +/* Actions that the smart transport can ask + * a subtransport to perform */ +typedef enum { + GIT_SERVICE_UPLOADPACK_LS = 1, + GIT_SERVICE_UPLOADPACK = 2, + GIT_SERVICE_RECEIVEPACK_LS = 3, + GIT_SERVICE_RECEIVEPACK = 4, +} git_smart_service_t; + +struct git_smart_subtransport; + +/* A stream used by the smart transport to read and write data + * from a subtransport */ +typedef struct git_smart_subtransport_stream { + /* The owning subtransport */ + struct git_smart_subtransport *subtransport; + + int (*read)( + struct git_smart_subtransport_stream *stream, + char *buffer, + size_t buf_size, + size_t *bytes_read); + + int (*write)( + struct git_smart_subtransport_stream *stream, + const char *buffer, + size_t len); + + void (*free)( + struct git_smart_subtransport_stream *stream); +} git_smart_subtransport_stream; + +/* An implementation of a subtransport which carries data for the + * smart transport */ +typedef struct git_smart_subtransport { + int (* action)( + git_smart_subtransport_stream **out, + struct git_smart_subtransport *transport, + const char *url, + git_smart_service_t action); + + /* Subtransports are guaranteed a call to close() between + * calls to action(), except for the following two "natural" progressions + * of actions against a constant URL. + * + * 1. UPLOADPACK_LS -> UPLOADPACK + * 2. RECEIVEPACK_LS -> RECEIVEPACK */ + int (* close)(struct git_smart_subtransport *transport); + + void (* free)(struct git_smart_subtransport *transport); +} git_smart_subtransport; + +/* A function which creates a new subtransport for the smart transport */ +typedef int (*git_smart_subtransport_cb)( + git_smart_subtransport **out, + git_transport* owner); + +typedef struct git_smart_subtransport_definition { + /* The function to use to create the git_smart_subtransport */ + git_smart_subtransport_cb callback; + + /* True if the protocol is stateless; false otherwise. For example, + * http:// is stateless, but git:// is not. */ + unsigned rpc; +} git_smart_subtransport_definition; + +/* Smart transport subtransports that come with libgit2 */ + +/** + * Create an instance of the http subtransport. This subtransport + * also supports https. On Win32, this subtransport may be implemented + * using the WinHTTP library. + * + * @param out The newly created subtransport + * @param owner The smart transport to own this subtransport + * @return 0 or an error code + */ +GIT_EXTERN(int) git_smart_subtransport_http( + git_smart_subtransport **out, + git_transport* owner); + +/** + * Create an instance of the git subtransport. + * + * @param out The newly created subtransport + * @param owner The smart transport to own this subtransport + * @return 0 or an error code + */ +GIT_EXTERN(int) git_smart_subtransport_git( + git_smart_subtransport **out, + git_transport* owner); + +/* + *** End interface for subtransports for the smart transport *** + */ + +/** @} */ +GIT_END_DECL +#endif |