include/git2/sys/transport.h

   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"
  12 #include "git2/types.h"
  13
  14 /**
  15  * @file git2/sys/transport.h
  16  * @brief Git custom transport registration interfaces and functions
  17  * @defgroup git_transport Git custom transport registration
  18  * @ingroup Git
  19  * @{
  20  */
  21
  22 GIT_BEGIN_DECL
  23
  24 typedef enum {
  25         GIT_TRANSPORTFLAGS_NONE = 0,
  26 } git_transport_flags_t;
  27
  28 typedef struct git_transport git_transport;
  29
  30 struct git_transport {
  31         unsigned int version;
  32         /* Set progress and error callbacks */
  33         int (*set_callbacks)(
  34                 git_transport *transport,
  35                 git_transport_message_cb progress_cb,
  36                 git_transport_message_cb error_cb,
  37                 git_transport_certificate_check_cb certificate_check_cb,
  38                 void *payload);
  39
  40         /* Connect the transport to the remote repository, using the given
  41          * direction. */
  42         int (*connect)(
  43                 git_transport *transport,
  44                 const char *url,
  45                 git_cred_acquire_cb cred_acquire_cb,
  46                 void *cred_acquire_payload,
  47                 int direction,
  48                 int flags);
  49
  50         /* This function may be called after a successful call to
  51          * connect(). The array returned is owned by the transport and
  52          * is guranteed until the next call of a transport function. */
  53         int (*ls)(
  54                 const git_remote_head ***out,
  55                 size_t *size,
  56                 git_transport *transport);
  57
  58         /* Executes the push whose context is in the git_push object. */
  59         int (*push)(git_transport *transport, git_push *push);
  60
  61         /* This function may be called after a successful call to connect(), when
  62          * the direction is FETCH. The function performs a negotiation to calculate
  63          * the wants list for the fetch. */
  64         int (*negotiate_fetch)(
  65                 git_transport *transport,
  66                 git_repository *repo,
  67                 const git_remote_head * const *refs,
  68                 size_t count);
  69
  70         /* This function may be called after a successful call to negotiate_fetch(),
  71          * when the direction is FETCH. This function retrieves the pack file for
  72          * the fetch from the remote end. */
  73         int (*download_pack)(
  74                 git_transport *transport,
  75                 git_repository *repo,
  76                 git_transfer_progress *stats,
  77                 git_transfer_progress_cb progress_cb,
  78                 void *progress_payload);
  79
  80         /* Checks to see if the transport is connected */
  81         int (*is_connected)(git_transport *transport);
  82
  83         /* Reads the flags value previously passed into connect() */
  84         int (*read_flags)(git_transport *transport, int *flags);
  85
  86         /* Cancels any outstanding transport operation */
  87         void (*cancel)(git_transport *transport);
  88
  89         /* This function is the reverse of connect() -- it terminates the
  90          * connection to the remote end. */
  91         int (*close)(git_transport *transport);
  92
  93         /* Frees/destructs the git_transport object. */
  94         void (*free)(git_transport *transport);
  95 };
  96
  97 #define GIT_TRANSPORT_VERSION 1
  98 #define GIT_TRANSPORT_INIT {GIT_TRANSPORT_VERSION}
  99
 100 /**
 101  * Initializes a `git_transport` with default values. Equivalent to
 102  * creating an instance with GIT_TRANSPORT_INIT.
 103  *
 104  * @param opts the `git_transport` struct to initialize
 105  * @param version Version of struct; pass `GIT_TRANSPORT_VERSION`
 106  * @return Zero on success; -1 on failure.
 107  */
 108 GIT_EXTERN(int) git_transport_init(
 109         git_transport *opts,
 110         unsigned int version);
 111
 112 /**
 113  * Function to use to create a transport from a URL. The transport database
 114  * is scanned to find a transport that implements the scheme of the URI (i.e.
 115  * git:// or http://) and a transport object is returned to the caller.
 116  *
 117  * @param out The newly created transport (out)
 118  * @param owner The git_remote which will own this transport
 119  * @param url The URL to connect to
 120  * @return 0 or an error code
 121  */
 122 GIT_EXTERN(int) git_transport_new(git_transport **out, git_remote *owner, const char *url);
 123
 124 /**
 125  * Create an ssh transport with custom git command paths
 126  *
 127  * This is a factory function suitable for setting as the transport
 128  * callback in a remote (or for a clone in the options).
 129  *
 130  * The payload argument must be a strarray pointer with the paths for
 131  * the `git-upload-pack` and `git-receive-pack` at index 0 and 1.
 132  *
 133  * @param out the resulting transport
 134  * @param owner the owning remote
 135  * @param payload a strarray with the paths
 136  * @return 0 or an error code
 137  */
 138 GIT_EXTERN(int) git_transport_ssh_with_paths(git_transport **out, git_remote *owner, void *payload);
 139
 140 /* Signature of a function which creates a transport */
 141 typedef int (*git_transport_cb)(git_transport **out, git_remote *owner, void *param);
 142
 143 /**
 144  * Add a custom transport definition, to be used in addition to the built-in
 145  * set of transports that come with libgit2.
 146  *
 147  * The caller is responsible for synchronizing calls to git_transport_register
 148  * and git_transport_unregister with other calls to the library that
 149  * instantiate transports.
 150  *
 151  * @param prefix The scheme (ending in "://") to match, i.e. "git://"
 152  * @param cb The callback used to create an instance of the transport
 153  * @param param A fixed parameter to pass to cb at creation time
 154  * @return 0 or an error code
 155  */
 156 GIT_EXTERN(int) git_transport_register(
 157         const char *prefix,
 158         git_transport_cb cb,
 159         void *param);
 160
 161 /**
 162  *
 163  * Unregister a custom transport definition which was previously registered
 164  * with git_transport_register.
 165  *
 166  * @param prefix From the previous call to git_transport_register
 167  * @return 0 or an error code
 168  */
 169 GIT_EXTERN(int) git_transport_unregister(
 170         const char *prefix);
 171
 172 /* Transports which come with libgit2 (match git_transport_cb). The expected
 173  * value for "param" is listed in-line below. */
 174
 175 /**
 176  * Create an instance of the dummy transport.
 177  *
 178  * @param out The newly created transport (out)
 179  * @param owner The git_remote which will own this transport
 180  * @param payload You must pass NULL for this parameter.
 181  * @return 0 or an error code
 182  */
 183 GIT_EXTERN(int) git_transport_dummy(
 184         git_transport **out,
 185         git_remote *owner,
 186         /* NULL */ void *payload);
 187
 188 /**
 189  * Create an instance of the local transport.
 190  *
 191  * @param out The newly created transport (out)
 192  * @param owner The git_remote which will own this transport
 193  * @param payload You must pass NULL for this parameter.
 194  * @return 0 or an error code
 195  */
 196 GIT_EXTERN(int) git_transport_local(
 197         git_transport **out,
 198         git_remote *owner,
 199         /* NULL */ void *payload);
 200
 201 /**
 202  * Create an instance of the smart transport.
 203  *
 204  * @param out The newly created transport (out)
 205  * @param owner The git_remote which will own this transport
 206  * @param payload A pointer to a git_smart_subtransport_definition
 207  * @return 0 or an error code
 208  */
 209 GIT_EXTERN(int) git_transport_smart(
 210         git_transport **out,
 211         git_remote *owner,
 212         /* (git_smart_subtransport_definition *) */ void *payload);
 213
 214 /*
 215  *** End of base transport interface ***
 216  *** Begin interface for subtransports for the smart transport ***
 217  */
 218
 219 /* The smart transport knows how to speak the git protocol, but it has no
 220  * knowledge of how to establish a connection between it and another endpoint,
 221  * or how to move data back and forth. For this, a subtransport interface is
 222  * declared, and the smart transport delegates this work to the subtransports.
 223  * Three subtransports are implemented: git, http, and winhttp. (The http and
 224  * winhttp transports each implement both http and https.) */
 225
 226 /* Subtransports can either be RPC = 0 (persistent connection) or RPC = 1
 227  * (request/response). The smart transport handles the differences in its own
 228  * logic. The git subtransport is RPC = 0, while http and winhttp are both
 229  * RPC = 1. */
 230
 231 /* Actions that the smart transport can ask
 232  * a subtransport to perform */
 233 typedef enum {
 234         GIT_SERVICE_UPLOADPACK_LS = 1,
 235         GIT_SERVICE_UPLOADPACK = 2,
 236         GIT_SERVICE_RECEIVEPACK_LS = 3,
 237         GIT_SERVICE_RECEIVEPACK = 4,
 238 } git_smart_service_t;
 239
 240 typedef struct git_smart_subtransport git_smart_subtransport;
 241 typedef struct git_smart_subtransport_stream git_smart_subtransport_stream;
 242
 243 /* A stream used by the smart transport to read and write data
 244  * from a subtransport */
 245 struct git_smart_subtransport_stream {
 246         /* The owning subtransport */
 247         git_smart_subtransport *subtransport;
 248
 249         int (*read)(
 250                 git_smart_subtransport_stream *stream,
 251                 char *buffer,
 252                 size_t buf_size,
 253                 size_t *bytes_read);
 254
 255         int (*write)(
 256                 git_smart_subtransport_stream *stream,
 257                 const char *buffer,
 258                 size_t len);
 259
 260         void (*free)(
 261                 git_smart_subtransport_stream *stream);
 262 };
 263
 264 /* An implementation of a subtransport which carries data for the
 265  * smart transport */
 266 struct git_smart_subtransport {
 267         int (* action)(
 268                         git_smart_subtransport_stream **out,
 269                         git_smart_subtransport *transport,
 270                         const char *url,
 271                         git_smart_service_t action);
 272
 273         /* Subtransports are guaranteed a call to close() between
 274          * calls to action(), except for the following two "natural" progressions
 275          * of actions against a constant URL.
 276          *
 277          * 1. UPLOADPACK_LS -> UPLOADPACK
 278          * 2. RECEIVEPACK_LS -> RECEIVEPACK */
 279         int (*close)(git_smart_subtransport *transport);
 280
 281         void (*free)(git_smart_subtransport *transport);
 282 };
 283
 284 /* A function which creates a new subtransport for the smart transport */
 285 typedef int (*git_smart_subtransport_cb)(
 286         git_smart_subtransport **out,
 287         git_transport* owner);
 288
 289 typedef struct git_smart_subtransport_definition {
 290         /* The function to use to create the git_smart_subtransport */
 291         git_smart_subtransport_cb callback;
 292
 293         /* True if the protocol is stateless; false otherwise. For example,
 294          * http:// is stateless, but git:// is not. */
 295         unsigned rpc;
 296 } git_smart_subtransport_definition;
 297
 298 /* Smart transport subtransports that come with libgit2 */
 299
 300 /**
 301  * Create an instance of the http subtransport. This subtransport
 302  * also supports https. On Win32, this subtransport may be implemented
 303  * using the WinHTTP library.
 304  *
 305  * @param out The newly created subtransport
 306  * @param owner The smart transport to own this subtransport
 307  * @return 0 or an error code
 308  */
 309 GIT_EXTERN(int) git_smart_subtransport_http(
 310         git_smart_subtransport **out,
 311         git_transport* owner);
 312
 313 /**
 314  * Create an instance of the git subtransport.
 315  *
 316  * @param out The newly created subtransport
 317  * @param owner The smart transport to own this subtransport
 318  * @return 0 or an error code
 319  */
 320 GIT_EXTERN(int) git_smart_subtransport_git(
 321         git_smart_subtransport **out,
 322         git_transport* owner);
 323
 324 /**
 325  * Create an instance of the ssh subtransport.
 326  *
 327  * @param out The newly created subtransport
 328  * @param owner The smart transport to own this subtransport
 329  * @return 0 or an error code
 330  */
 331 GIT_EXTERN(int) git_smart_subtransport_ssh(
 332         git_smart_subtransport **out,
 333         git_transport* owner);
 334
 335 /**
 336  * Sets a custom transport factory for the remote. The caller can use this
 337  * function to override the transport used for this remote when performing
 338  * network operations.
 339  *
 340  * @param remote the remote to configure
 341  * @param transport_cb the function to use to create a transport
 342  * @param payload opaque parameter passed to transport_cb
 343  * @return 0 or an error code
 344  */
 345 GIT_EXTERN(int) git_remote_set_transport(
 346         git_remote *remote,
 347         git_transport_cb transport_cb,
 348         void *payload);
 349
 350 /** @} */
 351 GIT_END_DECL
 352 #endif