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