]>
Commit | Line | Data |
---|---|---|
41fb1ca0 PK |
1 | /* |
2 | * Copyright (C) 2009-2012 the libgit2 contributors | |
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 | #ifndef INCLUDE_git_transport_h__ | |
8 | #define INCLUDE_git_transport_h__ | |
9 | ||
10 | #include "indexer.h" | |
11 | #include "net.h" | |
12 | ||
13 | /** | |
14 | * @file git2/transport.h | |
15 | * @brief Git transport interfaces and functions | |
16 | * @defgroup git_transport interfaces and functions | |
17 | * @ingroup Git | |
18 | * @{ | |
19 | */ | |
20 | GIT_BEGIN_DECL | |
21 | ||
22 | /* | |
091361f5 PK |
23 | *** Begin interface for credentials acquisition *** |
24 | */ | |
25 | ||
26 | typedef enum { | |
27 | /* git_cred_userpass_plaintext */ | |
28 | GIT_CREDTYPE_USERPASS_PLAINTEXT = 1, | |
29 | } git_credtype_t; | |
30 | ||
31 | /* The base structure for all credential types */ | |
32 | typedef struct git_cred { | |
33 | git_credtype_t credtype; | |
34 | void (*free)( | |
35 | struct git_cred *cred); | |
36 | } git_cred; | |
37 | ||
38 | /* A plaintext username and password */ | |
39 | typedef struct git_cred_userpass_plaintext { | |
40 | git_cred parent; | |
41 | char *username; | |
42 | char *password; | |
43 | } git_cred_userpass_plaintext; | |
44 | ||
45 | /** | |
46 | * Creates a new plain-text username and password credential object. | |
47 | * | |
48 | * @param cred The newly created credential object. | |
49 | * @param username The username of the credential. | |
50 | * @param password The password of the credential. | |
51 | */ | |
52 | GIT_EXTERN(int) git_cred_userpass_plaintext_new( | |
53 | git_cred **cred, | |
54 | const char *username, | |
55 | const char *password); | |
56 | ||
57 | /** | |
58 | * Signature of a function which acquires a credential object. | |
59 | * | |
60 | * @param cred The newly created credential object. | |
61 | * @param url The resource for which we are demanding a credential. | |
62 | * @param allowed_types A bitmask stating which cred types are OK to return. | |
63 | */ | |
64 | typedef int (*git_cred_acquire_cb)( | |
65 | git_cred **cred, | |
66 | const char *url, | |
67 | int allowed_types); | |
68 | ||
69 | /* | |
70 | *** End interface for credentials acquisition *** | |
41fb1ca0 PK |
71 | *** Begin base transport interface *** |
72 | */ | |
73 | ||
74 | typedef enum { | |
75 | GIT_TRANSPORTFLAGS_NONE = 0, | |
76 | /* If the connection is secured with SSL/TLS, the authenticity | |
77 | * of the server certificate should not be verified. */ | |
78 | GIT_TRANSPORTFLAGS_NO_CHECK_CERT = 1 | |
79 | } git_transport_flags_t; | |
80 | ||
81 | typedef void (*git_transport_message_cb)(const char *str, int len, void *data); | |
82 | ||
83 | typedef struct git_transport { | |
84 | /* Set progress and error callbacks */ | |
85 | int (*set_callbacks)(struct git_transport *transport, | |
86 | git_transport_message_cb progress_cb, | |
87 | git_transport_message_cb error_cb, | |
88 | void *payload); | |
89 | ||
90 | /* Connect the transport to the remote repository, using the given | |
91 | * direction. */ | |
92 | int (*connect)(struct git_transport *transport, | |
93 | const char *url, | |
091361f5 | 94 | git_cred_acquire_cb cred_acquire_cb, |
41fb1ca0 PK |
95 | int direction, |
96 | int flags); | |
97 | ||
98 | /* This function may be called after a successful call to connect(). The | |
99 | * provided callback is invoked for each ref discovered on the remote | |
100 | * end. */ | |
101 | int (*ls)(struct git_transport *transport, | |
102 | git_headlist_cb list_cb, | |
103 | void *payload); | |
104 | ||
105 | /* Reserved until push is implemented. */ | |
106 | int (*push)(struct git_transport *transport); | |
107 | ||
108 | /* This function may be called after a successful call to connect(), when | |
109 | * the direction is FETCH. The function performs a negotiation to calculate | |
110 | * the wants list for the fetch. */ | |
111 | int (*negotiate_fetch)(struct git_transport *transport, | |
112 | git_repository *repo, | |
113 | const git_remote_head * const *refs, | |
114 | size_t count); | |
115 | ||
116 | /* This function may be called after a successful call to negotiate_fetch(), | |
117 | * when the direction is FETCH. This function retrieves the pack file for | |
118 | * the fetch from the remote end. */ | |
119 | int (*download_pack)(struct git_transport *transport, | |
120 | git_repository *repo, | |
121 | git_transfer_progress *stats, | |
122 | git_transfer_progress_callback progress_cb, | |
123 | void *progress_payload); | |
124 | ||
125 | /* Checks to see if the transport is connected */ | |
126 | int (*is_connected)(struct git_transport *transport, int *connected); | |
127 | ||
128 | /* Reads the flags value previously passed into connect() */ | |
129 | int (*read_flags)(struct git_transport *transport, int *flags); | |
130 | ||
131 | /* Cancels any outstanding transport operation */ | |
132 | void (*cancel)(struct git_transport *transport); | |
133 | ||
134 | /* This function is the reverse of connect() -- it terminates the | |
135 | * connection to the remote end. */ | |
136 | int (*close)(struct git_transport *transport); | |
137 | ||
138 | /* Frees/destructs the git_transport object. */ | |
139 | void (*free)(struct git_transport *transport); | |
140 | } git_transport; | |
141 | ||
142 | /** | |
143 | * Function to use to create a transport from a URL. The transport database | |
144 | * is scanned to find a transport that implements the scheme of the URI (i.e. | |
145 | * git:// or http://) and a transport object is returned to the caller. | |
146 | * | |
147 | * @param transport The newly created transport (out) | |
148 | * @param url The URL to connect to | |
149 | * @return 0 or an error code | |
150 | */ | |
151 | GIT_EXTERN(int) git_transport_new(git_transport **transport, const char *url); | |
152 | ||
153 | /** | |
154 | * Function which checks to see if a transport could be created for the | |
155 | * given URL (i.e. checks to see if libgit2 has a transport that supports | |
156 | * the given URL's scheme) | |
157 | * | |
158 | * @param url The URL to check | |
159 | * @return Zero if the URL is not valid; nonzero otherwise | |
160 | */ | |
161 | GIT_EXTERN(int) git_transport_valid_url(const char *url); | |
162 | ||
163 | /* Signature of a function which creates a transport */ | |
164 | typedef int (*git_transport_cb)(git_transport **transport, void *param); | |
165 | ||
166 | /* Transports which come with libgit2 (match git_transport_cb). The expected | |
167 | * value for "param" is listed in-line below. */ | |
168 | ||
169 | /** | |
170 | * Create an instance of the dummy transport. | |
171 | * | |
172 | * @param transport The newly created transport (out) | |
173 | * @param param You must pass NULL for this parameter. | |
174 | * @return 0 or an error code | |
175 | */ | |
176 | GIT_EXTERN(int) git_transport_dummy( | |
177 | git_transport **transport, | |
178 | /* NULL */ void *param); | |
179 | ||
180 | /** | |
181 | * Create an instance of the local transport. | |
182 | * | |
183 | * @param transport The newly created transport (out) | |
184 | * @param param You must pass NULL for this parameter. | |
185 | * @return 0 or an error code | |
186 | */ | |
187 | GIT_EXTERN(int) git_transport_local( | |
188 | git_transport **transport, | |
189 | /* NULL */ void *param); | |
190 | ||
191 | /** | |
192 | * Create an instance of the smart transport. | |
193 | * | |
194 | * @param transport The newly created transport (out) | |
195 | * @param param A pointer to a git_smart_subtransport_definition | |
196 | * @return 0 or an error code | |
197 | */ | |
198 | GIT_EXTERN(int) git_transport_smart( | |
199 | git_transport **transport, | |
200 | /* (git_smart_subtransport_definition *) */ void *param); | |
201 | ||
202 | /* | |
203 | *** End of base transport interface *** | |
204 | *** Begin interface for subtransports for the smart transport *** | |
205 | */ | |
206 | ||
207 | /* The smart transport knows how to speak the git protocol, but it has no | |
208 | * knowledge of how to establish a connection between it and another endpoint, | |
209 | * or how to move data back and forth. For this, a subtransport interface is | |
210 | * declared, and the smart transport delegates this work to the subtransports. | |
211 | * Three subtransports are implemented: git, http, and winhttp. (The http and | |
212 | * winhttp transports each implement both http and https.) */ | |
213 | ||
214 | /* Subtransports can either be RPC = 0 (persistent connection) or RPC = 1 | |
215 | * (request/response). The smart transport handles the differences in its own | |
216 | * logic. The git subtransport is RPC = 0, while http and winhttp are both | |
217 | * RPC = 1. */ | |
218 | ||
219 | /* Actions that the smart transport can ask | |
220 | * a subtransport to perform */ | |
221 | typedef enum { | |
222 | GIT_SERVICE_UPLOADPACK_LS = 1, | |
223 | GIT_SERVICE_UPLOADPACK = 2, | |
224 | } git_smart_service_t; | |
225 | ||
226 | struct git_smart_subtransport; | |
227 | ||
228 | /* A stream used by the smart transport to read and write data | |
229 | * from a subtransport */ | |
230 | typedef struct git_smart_subtransport_stream { | |
231 | /* The owning subtransport */ | |
232 | struct git_smart_subtransport *subtransport; | |
233 | ||
234 | int (*read)( | |
235 | struct git_smart_subtransport_stream *stream, | |
236 | char *buffer, | |
237 | size_t buf_size, | |
238 | size_t *bytes_read); | |
239 | ||
240 | int (*write)( | |
241 | struct git_smart_subtransport_stream *stream, | |
242 | const char *buffer, | |
243 | size_t len); | |
244 | ||
245 | void (*free)( | |
246 | struct git_smart_subtransport_stream *stream); | |
247 | } git_smart_subtransport_stream; | |
248 | ||
249 | /* An implementation of a subtransport which carries data for the | |
250 | * smart transport */ | |
251 | typedef struct git_smart_subtransport { | |
252 | int (* action)( | |
253 | git_smart_subtransport_stream **out, | |
254 | struct git_smart_subtransport *transport, | |
255 | const char *url, | |
256 | git_smart_service_t action); | |
257 | ||
258 | void (* free)(struct git_smart_subtransport *transport); | |
259 | } git_smart_subtransport; | |
260 | ||
261 | /* A function which creates a new subtransport for the smart transport */ | |
262 | typedef int (*git_smart_subtransport_cb)( | |
263 | git_smart_subtransport **out, | |
264 | git_transport* owner); | |
265 | ||
266 | typedef struct git_smart_subtransport_definition { | |
267 | /* The function to use to create the git_smart_subtransport */ | |
268 | git_smart_subtransport_cb callback; | |
269 | /* True if the protocol is stateless; false otherwise. For example, | |
270 | * http:// is stateless, but git:// is not. */ | |
271 | unsigned rpc : 1; | |
272 | } git_smart_subtransport_definition; | |
273 | ||
274 | /* Smart transport subtransports that come with libgit2 */ | |
275 | ||
276 | /** | |
277 | * Create an instance of the http subtransport. This subtransport | |
278 | * also supports https. On Win32, this subtransport may be implemented | |
279 | * using the WinHTTP library. | |
280 | * | |
281 | * @param out The newly created subtransport | |
282 | * @param owner The smart transport to own this subtransport | |
283 | * @return 0 or an error code | |
284 | */ | |
285 | GIT_EXTERN(int) git_smart_subtransport_http( | |
286 | git_smart_subtransport **out, | |
287 | git_transport* owner); | |
288 | ||
289 | /** | |
290 | * Create an instance of the git subtransport. | |
291 | * | |
292 | * @param out The newly created subtransport | |
293 | * @param owner The smart transport to own this subtransport | |
294 | * @return 0 or an error code | |
295 | */ | |
296 | GIT_EXTERN(int) git_smart_subtransport_git( | |
297 | git_smart_subtransport **out, | |
298 | git_transport* owner); | |
299 | ||
300 | /* | |
301 | *** End interface for subtransports for the smart transport *** | |
302 | */ | |
303 | ||
304 | /** @} */ | |
305 | GIT_END_DECL | |
306 | #endif |