[libgit2.git] / include / git2 / sys / transport.h

/*
 * 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_sys_git_transport_h
#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
 * @brief Git custom transport registration interfaces and functions
 * @defgroup git_transport Git custom transport registration
 * @ingroup Git
 * @{
 */

GIT_BEGIN_DECL

struct git_transport {
	unsigned int version; /**< The struct version */

	/**
	 * Connect the transport to the remote repository, using the given
	 * direction.
	 */
	int GIT_CALLBACK(connect)(
		git_transport *transport,
		const char *url,
		int direction,
		const git_remote_connect_options *connect_opts);

	/**
	 * Resets the connect options for the given transport.  This
	 * is useful for updating settings or callbacks for an already
	 * connected transport.
	 */
	int GIT_CALLBACK(set_connect_opts)(
		git_transport *transport,
		const git_remote_connect_options *connect_opts);

	/**
	 * Gets the capabilities for this remote repository.
	 *
	 * This function may be called after a successful call to
	 * `connect()`.
	 */
	int GIT_CALLBACK(capabilities)(
		unsigned int *capabilities,
		git_transport *transport);

	/**
	 * 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 GIT_CALLBACK(push)(
		git_transport *transport,
		git_push *push);

	/**
	 * 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);

	/**
	 * 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_indexer_progress *stats);

	/** Checks to see if the transport is connected */
	int GIT_CALLBACK(is_connected)(git_transport *transport);

	/** Cancels any outstanding transport operation */
	void GIT_CALLBACK(cancel)(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 GIT_CALLBACK(free)(git_transport *transport);
};

#define GIT_TRANSPORT_VERSION 1
#define GIT_TRANSPORT_INIT {GIT_TRANSPORT_VERSION}

/**
 * Initializes a `git_transport` with default values. Equivalent to
 * creating an instance with GIT_TRANSPORT_INIT.
 *
 * @param opts the `git_transport` struct to initialize
 * @param version Version of struct; pass `GIT_TRANSPORT_VERSION`
 * @return Zero on success; -1 on failure.
 */
GIT_EXTERN(int) git_transport_init(
	git_transport *opts,
	unsigned int 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);

/**
 * Create an ssh transport with custom git command paths
 *
 * This is a factory function suitable for setting as the transport
 * callback in a remote (or for a clone in the options).
 *
 * The payload argument must be a strarray pointer with the paths for
 * the `git-upload-pack` and `git-receive-pack` at index 0 and 1.
 *
 * @param out the resulting transport
 * @param owner the owning remote
 * @param payload a strarray with the paths
 * @return 0 or an error code
 */
GIT_EXTERN(int) git_transport_ssh_with_paths(git_transport **out, git_remote *owner, void *payload);

/**
 * Add a custom transport definition, to be used in addition to the built-in
 * set of transports that come with libgit2.
 *
 * 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 The scheme (ending in "://") to match, i.e. "git://"
 * @param cb The callback used to create an instance of the transport
 * @param param A fixed parameter to pass to cb at creation time
 * @return 0 or an error code
 */
GIT_EXTERN(int) git_transport_register(
	const char *prefix,
	git_transport_cb cb,
	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_EXTERN(int) git_transport_unregister(
	const char *prefix);

/* 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);

/**
 * 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 ***
 */

/** 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;

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.
 *
 * This provides a customization point in case you need to
 * support some other communication method.
 */
struct git_smart_subtransport_stream {
	git_smart_subtransport *subtransport; /**< The owning subtransport */

	/**
	 * 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);

	/**
	 * 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);

	/** Free the stream */
	void GIT_CALLBACK(free)(
		git_smart_subtransport_stream *stream);
};

/**
 * An implementation of a subtransport which carries data for the
 * smart transport
 */
struct git_smart_subtransport {
	/**
	 * 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);

	/**
	 * 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:
	 *
	 * - UPLOADPACK_LS -> UPLOADPACK
	 * - RECEIVEPACK_LS -> RECEIVEPACK
	 */
	int GIT_CALLBACK(close)(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_CALLBACK(git_smart_subtransport_cb)(
	git_smart_subtransport **out,
	git_transport *owner,
	void *param);

/**
 * Definition for a "subtransport"
 *
 * 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 */
	git_smart_subtransport_cb callback;

	/**
	 * True if the protocol is stateless; false otherwise. For example,
	 * 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.
 *
 * @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,
	void *param);

/**
 * 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,
	void *param);

/**
 * Create an instance of the ssh 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_ssh(
	git_smart_subtransport **out,
	git_transport *owner,
	void *param);

/** @} */
GIT_END_DECL
#endif
Commit	Line	Data
c180c065 ET	1	/*
	2	* Copyright (C) the libgit2 contributors. All rights reserved.
	3	*
	4	* This file is part of libgit2, distributed under the GNU GPL v2 with
	5	* a Linking Exception. For full terms see the included COPYING file.
	6	*/
	7
	8	#ifndef INCLUDE_sys_git_transport_h
	9	#define INCLUDE_sys_git_transport_h
	10
	11	#include "git2/net.h"
c25aa7cd	12	#include "git2/transport.h"
c180c065	13	#include "git2/types.h"
bf28da47	14	#include "git2/strarray.h"
07bd3e57	15	#include "git2/proxy.h"
c180c065 ET	16
	17	/**
	18	* @file git2/sys/transport.h
	19	* @brief Git custom transport registration interfaces and functions
	20	* @defgroup git_transport Git custom transport registration
	21	* @ingroup Git
	22	* @{
	23	*/
	24
	25	GIT_BEGIN_DECL
	26
c180c065	27	struct git_transport {
ac3d33df JK	28	unsigned int version; /*< The struct version /
ac3d33df JK	29
ac3d33df JK	30	/**
	31	* Connect the transport to the remote repository, using the given
	32	* direction.
	33	*/
	34	int GIT_CALLBACK(connect)(
c180c065 ET	35	git_transport *transport,
c180c065 ET	36	const char *url,
c180c065	37	int direction,
e579e0f7 MB	38	const git_remote_connect_options *connect_opts);
	39
	40	/**
	41	* Resets the connect options for the given transport. This
	42	* is useful for updating settings or callbacks for an already
	43	* connected transport.
	44	*/
	45	int GIT_CALLBACK(set_connect_opts)(
	46	git_transport *transport,
	47	const git_remote_connect_options *connect_opts);
	48
	49	/**
	50	* Gets the capabilities for this remote repository.
	51	*
	52	* This function may be called after a successful call to
	53	* `connect()`.
	54	*/
	55	int GIT_CALLBACK(capabilities)(
	56	unsigned int *capabilities,
	57	git_transport *transport);
c180c065	58
ac3d33df JK	59	/**
	60	* Get the list of available references in the remote repository.
	61	*
	62	* This function may be called after a successful call to
	63	* `connect()`. The array returned is owned by the transport and
	64	* must be kept valid until the next call to one of its functions.
	65	*/
	66	int GIT_CALLBACK(ls)(
c180c065 ET	67	const git_remote_head ***out,
	68	size_t *size,
	69	git_transport *transport);
	70
ac3d33df	71	/** Executes the push whose context is in the git_push object. */
e579e0f7 MB	72	int GIT_CALLBACK(push)(
	73	git_transport *transport,
	74	git_push *push);
c180c065	75
ac3d33df JK	76	/**
	77	* Negotiate a fetch with the remote repository.
	78	*
	79	* This function may be called after a successful call to `connect()`,
	80	* when the direction is GIT_DIRECTION_FETCH. The function performs a
	81	* negotiation to calculate the `wants` list for the fetch.
	82	*/
	83	int GIT_CALLBACK(negotiate_fetch)(
c180c065 ET	84	git_transport *transport,
	85	git_repository *repo,
	86	const git_remote_head * const *refs,
	87	size_t count);
	88
ac3d33df JK	89	/**
	90	* Start downloading the packfile from the remote repository.
	91	*
	92	* This function may be called after a successful call to
	93	* negotiate_fetch(), when the direction is GIT_DIRECTION_FETCH.
	94	*/
	95	int GIT_CALLBACK(download_pack)(
c180c065 ET	96	git_transport *transport,
c180c065 ET	97	git_repository *repo,
e579e0f7	98	git_indexer_progress *stats);
c180c065	99
ac3d33df JK	100	/** Checks to see if the transport is connected */
ac3d33df JK	101	int GIT_CALLBACK(is_connected)(git_transport *transport);
c180c065	102
ac3d33df JK	103	/** Cancels any outstanding transport operation */
ac3d33df JK	104	void GIT_CALLBACK(cancel)(git_transport *transport);
c180c065	105
ac3d33df JK	106	/**
	107	* Close the connection to the remote repository.
	108	*
	109	* This function is the reverse of connect() -- it terminates the
	110	* connection to the remote end.
	111	*/
	112	int GIT_CALLBACK(close)(git_transport *transport);
c180c065	113
ac3d33df JK	114	/** Frees/destructs the git_transport object. */
ac3d33df JK	115	void GIT_CALLBACK(free)(git_transport *transport);
c180c065 ET	116	};
	117
	118	#define GIT_TRANSPORT_VERSION 1
	119	#define GIT_TRANSPORT_INIT {GIT_TRANSPORT_VERSION}
	120
	121	/**
	122	* Initializes a `git_transport` with default values. Equivalent to
	123	* creating an instance with GIT_TRANSPORT_INIT.
	124	*
	125	* @param opts the `git_transport` struct to initialize
	126	* @param version Version of struct; pass `GIT_TRANSPORT_VERSION`
	127	* @return Zero on success; -1 on failure.
	128	*/
	129	GIT_EXTERN(int) git_transport_init(
	130	git_transport *opts,
	131	unsigned int version);
	132
	133	/**
	134	* Function to use to create a transport from a URL. The transport database
	135	* is scanned to find a transport that implements the scheme of the URI (i.e.
	136	* git:// or http://) and a transport object is returned to the caller.
	137	*
	138	* @param out The newly created transport (out)
	139	* @param owner The git_remote which will own this transport
	140	* @param url The URL to connect to
	141	* @return 0 or an error code
	142	*/
	143	GIT_EXTERN(int) git_transport_new(git_transport *out, git_remote owner, const char *url);
	144
	145	/**
	146	* Create an ssh transport with custom git command paths
	147	*
	148	* This is a factory function suitable for setting as the transport
	149	* callback in a remote (or for a clone in the options).
	150	*
	151	* The payload argument must be a strarray pointer with the paths for
	152	* the `git-upload-pack` and `git-receive-pack` at index 0 and 1.
	153	*
	154	* @param out the resulting transport
	155	* @param owner the owning remote
	156	* @param payload a strarray with the paths
	157	* @return 0 or an error code
	158	*/
	159	GIT_EXTERN(int) git_transport_ssh_with_paths(git_transport *out, git_remote owner, void *payload);
	160
c180c065 ET	161	/**
	162	* Add a custom transport definition, to be used in addition to the built-in
	163	* set of transports that come with libgit2.
	164	*
	165	* The caller is responsible for synchronizing calls to git_transport_register
	166	* and git_transport_unregister with other calls to the library that
	167	* instantiate transports.
	168	*
	169	* @param prefix The scheme (ending in "://") to match, i.e. "git://"
	170	* @param cb The callback used to create an instance of the transport
	171	* @param param A fixed parameter to pass to cb at creation time
	172	* @return 0 or an error code
	173	*/
	174	GIT_EXTERN(int) git_transport_register(
	175	const char *prefix,
	176	git_transport_cb cb,
	177	void *param);
	178
	179	/**
c180c065 ET	180	* Unregister a custom transport definition which was previously registered
	181	* with git_transport_register.
	182	*
ac3d33df JK	183	* The caller is responsible for synchronizing calls to git_transport_register
	184	* and git_transport_unregister with other calls to the library that
	185	* instantiate transports.
	186	*
c180c065 ET	187	* @param prefix From the previous call to git_transport_register
	188	* @return 0 or an error code
	189	*/
	190	GIT_EXTERN(int) git_transport_unregister(
	191	const char *prefix);
	192
	193	/* Transports which come with libgit2 (match git_transport_cb). The expected
	194	* value for "param" is listed in-line below. */
	195
	196	/**
	197	* Create an instance of the dummy transport.
	198	*
	199	* @param out The newly created transport (out)
	200	* @param owner The git_remote which will own this transport
	201	* @param payload You must pass NULL for this parameter.
	202	* @return 0 or an error code
	203	*/
	204	GIT_EXTERN(int) git_transport_dummy(
	205	git_transport **out,
	206	git_remote *owner,
	207	/* NULL / void payload);
	208
	209	/**
	210	* Create an instance of the local transport.
	211	*
	212	* @param out The newly created transport (out)
	213	* @param owner The git_remote which will own this transport
	214	* @param payload You must pass NULL for this parameter.
	215	* @return 0 or an error code
	216	*/
	217	GIT_EXTERN(int) git_transport_local(
	218	git_transport **out,
	219	git_remote *owner,
	220	/* NULL / void payload);
	221
	222	/**
	223	* Create an instance of the smart transport.
	224	*
	225	* @param out The newly created transport (out)
	226	* @param owner The git_remote which will own this transport
	227	* @param payload A pointer to a git_smart_subtransport_definition
	228	* @return 0 or an error code
	229	*/
	230	GIT_EXTERN(int) git_transport_smart(
	231	git_transport **out,
	232	git_remote *owner,
	233	/* (git_smart_subtransport_definition ) / void *payload);
	234
47ed7e5a CMN	235	/**
	236	* Call the certificate check for this transport.
	237	*
	238	* @param transport a smart transport
	239	* @param cert the certificate to pass to the caller
	240	* @param valid whether we believe the certificate is valid
	241	* @param hostname the hostname we connected to
ac3d33df JK	242	* @return the return value of the callback: 0 for no error, GIT_PASSTHROUGH
	243	* to indicate that there is no callback registered (or the callback
	244	* refused to validate the certificate and callers should behave as
	245	* if no callback was set), or < 0 for an error
47ed7e5a CMN	246	*/
	247	GIT_EXTERN(int) git_transport_smart_certificate_check(git_transport transport, git_cert cert, int valid, const char *hostname);
	248
	249	/**
	250	* Call the credentials callback for this transport
	251	*
	252	* @param out the pointer where the creds are to be stored
	253	* @param transport a smart transport
	254	* @param user the user we saw on the url (if any)
	255	* @param methods available methods for authentication
ac3d33df JK	256	* @return the return value of the callback: 0 for no error, GIT_PASSTHROUGH
	257	* to indicate that there is no callback registered (or the callback
	258	* refused to provide credentials and callers should behave as if no
	259	* callback was set), or < 0 for an error
47ed7e5a	260	*/
22a2d3d5	261	GIT_EXTERN(int) git_transport_smart_credentials(git_credential *out, git_transport transport, const char *user, int methods);
47ed7e5a	262
5c760960 CMN	263	/**
	264	* Get a copy of the proxy options
	265	*
	266	* The url is copied and must be freed by the caller.
	267	*
	268	* @param out options struct to fill
	269	* @param transport the transport to extract the data from.
	270	*/
	271	GIT_EXTERN(int) git_transport_smart_proxy_options(git_proxy_options out, git_transport transport);
	272
c180c065 ET	273	/*
	274	* End of base transport interface *
	275	* Begin interface for subtransports for the smart transport *
	276	*/
	277
ac3d33df	278	/** Actions that the smart transport can ask a subtransport to perform */
c180c065 ET	279	typedef enum {
	280	GIT_SERVICE_UPLOADPACK_LS = 1,
	281	GIT_SERVICE_UPLOADPACK = 2,
	282	GIT_SERVICE_RECEIVEPACK_LS = 3,
e579e0f7	283	GIT_SERVICE_RECEIVEPACK = 4
c180c065 ET	284	} git_smart_service_t;
	285
	286	typedef struct git_smart_subtransport git_smart_subtransport;
	287	typedef struct git_smart_subtransport_stream git_smart_subtransport_stream;
	288
ac3d33df JK	289	/**
	290	* A stream used by the smart transport to read and write data
	291	* from a subtransport.
	292	*
	293	* This provides a customization point in case you need to
	294	* support some other communication method.
	295	*/
c180c065	296	struct git_smart_subtransport_stream {
ac3d33df	297	git_smart_subtransport subtransport; /< The owning subtransport /
c180c065	298
ac3d33df JK	299	/**
	300	* Read available data from the stream.
	301	*
	302	* The implementation may read less than requested.
	303	*/
	304	int GIT_CALLBACK(read)(
c180c065 ET	305	git_smart_subtransport_stream *stream,
	306	char *buffer,
	307	size_t buf_size,
	308	size_t *bytes_read);
	309
ac3d33df JK	310	/**
	311	* Write data to the stream
	312	*
	313	* The implementation must write all data or return an error.
	314	*/
	315	int GIT_CALLBACK(write)(
c180c065 ET	316	git_smart_subtransport_stream *stream,
	317	const char *buffer,
	318	size_t len);
	319
ac3d33df JK	320	/** Free the stream */
ac3d33df JK	321	void GIT_CALLBACK(free)(
c180c065 ET	322	git_smart_subtransport_stream *stream);
	323	};
	324
ac3d33df JK	325	/**
	326	* An implementation of a subtransport which carries data for the
	327	* smart transport
	328	*/
c180c065	329	struct git_smart_subtransport {
ac3d33df JK	330	/**
	331	* Setup a subtransport stream for the requested action.
	332	*/
	333	int GIT_CALLBACK(action)(
c180c065 ET	334	git_smart_subtransport_stream **out,
	335	git_smart_subtransport *transport,
	336	const char *url,
	337	git_smart_service_t action);
	338
ac3d33df JK	339	/**
	340	* Close the subtransport.
	341	*
	342	* Subtransports are guaranteed a call to close() between
c180c065	343	* calls to action(), except for the following two "natural" progressions
ac3d33df	344	* of actions against a constant URL:
c180c065	345	*
ac3d33df JK	346	* - UPLOADPACK_LS -> UPLOADPACK
	347	* - RECEIVEPACK_LS -> RECEIVEPACK
	348	*/
	349	int GIT_CALLBACK(close)(git_smart_subtransport *transport);
c180c065	350
ac3d33df JK	351	/** Free the subtransport */
ac3d33df JK	352	void GIT_CALLBACK(free)(git_smart_subtransport *transport);
c180c065 ET	353	};
c180c065 ET	354
ac3d33df JK	355	/** A function which creates a new subtransport for the smart transport */
ac3d33df JK	356	typedef int GIT_CALLBACK(git_smart_subtransport_cb)(
c180c065	357	git_smart_subtransport **out,
ac3d33df JK	358	git_transport *owner,
ac3d33df JK	359	void *param);
c180c065	360
a295bd2d CMN	361	/**
	362	* Definition for a "subtransport"
	363	*
ac3d33df JK	364	* The smart transport knows how to speak the git protocol, but it has no
	365	* knowledge of how to establish a connection between it and another endpoint,
	366	* or how to move data back and forth. For this, a subtransport interface is
	367	* declared, and the smart transport delegates this work to the subtransports.
	368	*
	369	* Three subtransports are provided by libgit2: ssh, git, http(s).
	370	*
	371	* Subtransports can either be RPC = 0 (persistent connection) or RPC = 1
	372	* (request/response). The smart transport handles the differences in its own
	373	* logic. The git subtransport is RPC = 0, while http is RPC = 1.
a295bd2d	374	*/
c180c065	375	typedef struct git_smart_subtransport_definition {
a295bd2d	376	/** The function to use to create the git_smart_subtransport */
c180c065 ET	377	git_smart_subtransport_cb callback;
c180c065 ET	378
a295bd2d CMN	379	/**
	380	* True if the protocol is stateless; false otherwise. For example,
	381	* http:// is stateless, but git:// is not.
	382	*/
c180c065	383	unsigned rpc;
142e5379	384
ac3d33df JK	385	/** User-specified parameter passed to the callback */
ac3d33df JK	386	void *param;
c180c065 ET	387	} git_smart_subtransport_definition;
	388
	389	/* Smart transport subtransports that come with libgit2 */
	390
	391	/**
ac3d33df JK	392	* Create an instance of the http subtransport.
	393	*
	394	* This subtransport also supports https.
c180c065 ET	395	*
	396	* @param out The newly created subtransport
	397	* @param owner The smart transport to own this subtransport
	398	* @return 0 or an error code
	399	*/
	400	GIT_EXTERN(int) git_smart_subtransport_http(
	401	git_smart_subtransport **out,
ac3d33df	402	git_transport *owner,
142e5379	403	void *param);
c180c065 ET	404
	405	/**
	406	* Create an instance of the git subtransport.
	407	*
	408	* @param out The newly created subtransport
	409	* @param owner The smart transport to own this subtransport
	410	* @return 0 or an error code
	411	*/
	412	GIT_EXTERN(int) git_smart_subtransport_git(
	413	git_smart_subtransport **out,
ac3d33df	414	git_transport *owner,
142e5379	415	void *param);
c180c065 ET	416
	417	/**
	418	* Create an instance of the ssh subtransport.
	419	*
	420	* @param out The newly created subtransport
	421	* @param owner The smart transport to own this subtransport
	422	* @return 0 or an error code
	423	*/
	424	GIT_EXTERN(int) git_smart_subtransport_ssh(
	425	git_smart_subtransport **out,
ac3d33df	426	git_transport *owner,
142e5379	427	void *param);
c180c065	428
c180c065 ET	429	/** @} */
	430	GIT_END_DECL
	431	#endif