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