#define INCLUDE_sys_git_transport_h
#include "git2/net.h"
+#include "git2/transport.h"
#include "git2/types.h"
+#include "git2/strarray.h"
+#include "git2/proxy.h"
/**
* @file git2/sys/transport.h
GIT_TRANSPORTFLAGS_NONE = 0,
} git_transport_flags_t;
-typedef struct git_transport git_transport;
-
struct git_transport {
- unsigned int version;
- /* Set progress and error callbacks */
- int (*set_callbacks)(
+ unsigned int version; /**< The struct version */
+
+ /** Set progress and error callbacks */
+ int GIT_CALLBACK(set_callbacks)(
git_transport *transport,
git_transport_message_cb progress_cb,
git_transport_message_cb error_cb,
git_transport_certificate_check_cb certificate_check_cb,
void *payload);
- /* Connect the transport to the remote repository, using the given
- * direction. */
- int (*connect)(
+ /** Set custom headers for HTTP requests */
+ int GIT_CALLBACK(set_custom_headers)(
+ git_transport *transport,
+ const git_strarray *custom_headers);
+
+ /**
+ * Connect the transport to the remote repository, using the given
+ * direction.
+ */
+ int GIT_CALLBACK(connect)(
git_transport *transport,
const char *url,
- git_cred_acquire_cb cred_acquire_cb,
+ git_credential_acquire_cb cred_acquire_cb,
void *cred_acquire_payload,
+ const git_proxy_options *proxy_opts,
int direction,
int flags);
- /* This function may be called after a successful call to
- * connect(). The array returned is owned by the transport and
- * is guaranteed until the next call of a transport function. */
- int (*ls)(
+ /**
+ * Get the list of available references in the remote repository.
+ *
+ * This function may be called after a successful call to
+ * `connect()`. The array returned is owned by the transport and
+ * must be kept valid until the next call to one of its functions.
+ */
+ int GIT_CALLBACK(ls)(
const git_remote_head ***out,
size_t *size,
git_transport *transport);
- /* Executes the push whose context is in the git_push object. */
- int (*push)(git_transport *transport, git_push *push);
+ /** Executes the push whose context is in the git_push object. */
+ int GIT_CALLBACK(push)(git_transport *transport, git_push *push, const git_remote_callbacks *callbacks);
- /* 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)(
+ /**
+ * Negotiate a fetch with the remote repository.
+ *
+ * This function may be called after a successful call to `connect()`,
+ * when the direction is GIT_DIRECTION_FETCH. The function performs a
+ * negotiation to calculate the `wants` list for the fetch.
+ */
+ int GIT_CALLBACK(negotiate_fetch)(
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)(
+ /**
+ * Start downloading the packfile from the remote repository.
+ *
+ * This function may be called after a successful call to
+ * negotiate_fetch(), when the direction is GIT_DIRECTION_FETCH.
+ */
+ int GIT_CALLBACK(download_pack)(
git_transport *transport,
git_repository *repo,
- git_transfer_progress *stats,
- git_transfer_progress_cb progress_cb,
+ git_indexer_progress *stats,
+ git_indexer_progress_cb progress_cb,
void *progress_payload);
- /* Checks to see if the transport is connected */
- int (*is_connected)(git_transport *transport);
+ /** Checks to see if the transport is connected */
+ int GIT_CALLBACK(is_connected)(git_transport *transport);
- /* Reads the flags value previously passed into connect() */
- int (*read_flags)(git_transport *transport, int *flags);
+ /** Reads the flags value previously passed into connect() */
+ int GIT_CALLBACK(read_flags)(git_transport *transport, int *flags);
- /* Cancels any outstanding transport operation */
- void (*cancel)(git_transport *transport);
+ /** Cancels any outstanding transport operation */
+ void GIT_CALLBACK(cancel)(git_transport *transport);
- /* This function is the reverse of connect() -- it terminates the
- * connection to the remote end. */
- int (*close)(git_transport *transport);
+ /**
+ * Close the connection to the remote repository.
+ *
+ * This function is the reverse of connect() -- it terminates the
+ * connection to the remote end.
+ */
+ int GIT_CALLBACK(close)(git_transport *transport);
- /* Frees/destructs the git_transport object. */
- void (*free)(git_transport *transport);
+ /** Frees/destructs the git_transport object. */
+ void GIT_CALLBACK(free)(git_transport *transport);
};
#define GIT_TRANSPORT_VERSION 1
*/
GIT_EXTERN(int) git_transport_ssh_with_paths(git_transport **out, git_remote *owner, void *payload);
-/* Signature of a function which creates a transport */
-typedef int (*git_transport_cb)(git_transport **out, git_remote *owner, void *param);
-
/**
* Add a custom transport definition, to be used in addition to the built-in
* set of transports that come with libgit2.
void *param);
/**
- *
* Unregister a custom transport definition which was previously registered
* with git_transport_register.
*
+ * The caller is responsible for synchronizing calls to git_transport_register
+ * and git_transport_unregister with other calls to the library that
+ * instantiate transports.
+ *
* @param prefix From the previous call to git_transport_register
* @return 0 or an error code
*/
git_remote *owner,
/* (git_smart_subtransport_definition *) */ void *payload);
+/**
+ * Call the certificate check for this transport.
+ *
+ * @param transport a smart transport
+ * @param cert the certificate to pass to the caller
+ * @param valid whether we believe the certificate is valid
+ * @param hostname the hostname we connected to
+ * @return the return value of the callback: 0 for no error, GIT_PASSTHROUGH
+ * to indicate that there is no callback registered (or the callback
+ * refused to validate the certificate and callers should behave as
+ * if no callback was set), or < 0 for an error
+ */
+GIT_EXTERN(int) git_transport_smart_certificate_check(git_transport *transport, git_cert *cert, int valid, const char *hostname);
+
+/**
+ * Call the credentials callback for this transport
+ *
+ * @param out the pointer where the creds are to be stored
+ * @param transport a smart transport
+ * @param user the user we saw on the url (if any)
+ * @param methods available methods for authentication
+ * @return the return value of the callback: 0 for no error, GIT_PASSTHROUGH
+ * to indicate that there is no callback registered (or the callback
+ * refused to provide credentials and callers should behave as if no
+ * callback was set), or < 0 for an error
+ */
+GIT_EXTERN(int) git_transport_smart_credentials(git_credential **out, git_transport *transport, const char *user, int methods);
+
+/**
+ * Get a copy of the proxy options
+ *
+ * The url is copied and must be freed by the caller.
+ *
+ * @param out options struct to fill
+ * @param transport the transport to extract the data from.
+ */
+GIT_EXTERN(int) git_transport_smart_proxy_options(git_proxy_options *out, git_transport *transport);
+
/*
*** 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 */
+/** Actions that the smart transport can ask a subtransport to perform */
typedef enum {
GIT_SERVICE_UPLOADPACK_LS = 1,
GIT_SERVICE_UPLOADPACK = 2,
typedef struct git_smart_subtransport git_smart_subtransport;
typedef struct git_smart_subtransport_stream git_smart_subtransport_stream;
-/* A stream used by the smart transport to read and write data
- * from a subtransport */
+/**
+ * A stream used by the smart transport to read and write data
+ * from a subtransport.
+ *
+ * This provides a customization point in case you need to
+ * support some other communication method.
+ */
struct git_smart_subtransport_stream {
- /* The owning subtransport */
- git_smart_subtransport *subtransport;
+ git_smart_subtransport *subtransport; /**< The owning subtransport */
- int (*read)(
+ /**
+ * Read available data from the stream.
+ *
+ * The implementation may read less than requested.
+ */
+ int GIT_CALLBACK(read)(
git_smart_subtransport_stream *stream,
char *buffer,
size_t buf_size,
size_t *bytes_read);
- int (*write)(
+ /**
+ * Write data to the stream
+ *
+ * The implementation must write all data or return an error.
+ */
+ int GIT_CALLBACK(write)(
git_smart_subtransport_stream *stream,
const char *buffer,
size_t len);
- void (*free)(
+ /** Free the stream */
+ void GIT_CALLBACK(free)(
git_smart_subtransport_stream *stream);
};
-/* An implementation of a subtransport which carries data for the
- * smart transport */
+/**
+ * An implementation of a subtransport which carries data for the
+ * smart transport
+ */
struct git_smart_subtransport {
- int (* action)(
+ /**
+ * Setup a subtransport stream for the requested action.
+ */
+ int GIT_CALLBACK(action)(
git_smart_subtransport_stream **out,
git_smart_subtransport *transport,
const char *url,
git_smart_service_t action);
- /* Subtransports are guaranteed a call to close() between
+ /**
+ * Close the subtransport.
+ *
+ * Subtransports are guaranteed a call to close() between
* calls to action(), except for the following two "natural" progressions
- * of actions against a constant URL.
+ * of actions against a constant URL:
*
- * 1. UPLOADPACK_LS -> UPLOADPACK
- * 2. RECEIVEPACK_LS -> RECEIVEPACK */
- int (*close)(git_smart_subtransport *transport);
+ * - UPLOADPACK_LS -> UPLOADPACK
+ * - RECEIVEPACK_LS -> RECEIVEPACK
+ */
+ int GIT_CALLBACK(close)(git_smart_subtransport *transport);
- void (*free)(git_smart_subtransport *transport);
+ /** Free the subtransport */
+ void GIT_CALLBACK(free)(git_smart_subtransport *transport);
};
-/* A function which creates a new subtransport for the smart transport */
-typedef int (*git_smart_subtransport_cb)(
+/** A function which creates a new subtransport for the smart transport */
+typedef int GIT_CALLBACK(git_smart_subtransport_cb)(
git_smart_subtransport **out,
- git_transport* owner);
+ git_transport *owner,
+ void *param);
/**
* Definition for a "subtransport"
*
- * This is used to let the smart protocol code know about the protocol
- * which you are implementing.
+ * 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 provided by libgit2: ssh, git, http(s).
+ *
+ * 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 is RPC = 1.
*/
typedef struct git_smart_subtransport_definition {
/** The function to use to create the git_smart_subtransport */
* http:// is stateless, but git:// is not.
*/
unsigned rpc;
+
+ /** User-specified parameter passed to the callback */
+ void *param;
} 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.
+ * Create an instance of the http subtransport.
+ *
+ * This subtransport also supports https.
*
* @param out The newly created subtransport
* @param owner The smart transport to own this subtransport
*/
GIT_EXTERN(int) git_smart_subtransport_http(
git_smart_subtransport **out,
- git_transport* owner);
+ git_transport *owner,
+ void *param);
/**
* Create an instance of the git subtransport.
*/
GIT_EXTERN(int) git_smart_subtransport_git(
git_smart_subtransport **out,
- git_transport* owner);
+ git_transport *owner,
+ void *param);
/**
* Create an instance of the ssh subtransport.
*/
GIT_EXTERN(int) git_smart_subtransport_ssh(
git_smart_subtransport **out,
- git_transport* owner);
-
-/**
- * Sets a custom transport factory for the remote. The caller can use this
- * function to override the transport used for this remote when performing
- * network operations.
- *
- * @param remote the remote to configure
- * @param transport_cb the function to use to create a transport
- * @param payload opaque parameter passed to transport_cb
- * @return 0 or an error code
- */
-GIT_EXTERN(int) git_remote_set_transport(
- git_remote *remote,
- git_transport_cb transport_cb,
- void *payload);
+ git_transport *owner,
+ void *param);
/** @} */
GIT_END_DECL
projects / libgit2.git / blobdiff