]>
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" | |
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, | |
c180c065 ET |
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, | |
9b940586 | 37 | git_transport_certificate_check_cb certificate_check_cb, |
c180c065 ET |
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 | |
b874629b | 52 | * is guaranteed until the next call of a transport function. */ |
c180c065 ET |
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 |