2 * Copyright (C) the libgit2 contributors. All rights reserved.
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.
8 #ifndef INCLUDE_transports_httpclient_h__
9 #define INCLUDE_transports_httpclient_h__
14 #define GIT_HTTP_STATUS_CONTINUE 100
15 #define GIT_HTTP_STATUS_OK 200
16 #define GIT_HTTP_MOVED_PERMANENTLY 301
17 #define GIT_HTTP_FOUND 302
18 #define GIT_HTTP_SEE_OTHER 303
19 #define GIT_HTTP_TEMPORARY_REDIRECT 307
20 #define GIT_HTTP_PERMANENT_REDIRECT 308
21 #define GIT_HTTP_STATUS_UNAUTHORIZED 401
22 #define GIT_HTTP_STATUS_PROXY_AUTHENTICATION_REQUIRED 407
24 typedef struct git_http_client git_http_client
;
26 /** Method for the HTTP request */
30 GIT_HTTP_METHOD_CONNECT
33 /** An HTTP request */
35 git_http_method method
; /**< Method for the request */
36 git_net_url
*url
; /**< Full request URL */
37 git_net_url
*proxy
; /**< Proxy to use */
40 const char *accept
; /**< Contents of the Accept header */
41 const char *content_type
; /**< Content-Type header (for POST) */
42 git_credential
*credentials
; /**< Credentials to authenticate with */
43 git_credential
*proxy_credentials
; /**< Credentials for proxy */
44 git_strarray
*custom_headers
; /**< Additional headers to deliver */
46 /* To POST a payload, either set content_length OR set chunked. */
47 size_t content_length
; /**< Length of the POST body */
48 unsigned chunked
: 1, /**< Post with chunking */
49 expect_continue
: 1; /**< Use expect/continue negotiation */
57 size_t content_length
;
60 /* Authentication headers */
61 unsigned server_auth_schemetypes
; /**< Schemes requested by remote */
62 unsigned server_auth_credtypes
; /**< Supported cred types for remote */
64 unsigned proxy_auth_schemetypes
; /**< Schemes requested by proxy */
65 unsigned proxy_auth_credtypes
; /**< Supported cred types for proxy */
67 unsigned chunked
: 1, /**< Response body is chunked */
68 resend_credentials
: 1; /**< Resend with authentication */
72 /** Certificate check callback for the remote */
73 git_transport_certificate_check_cb server_certificate_check_cb
;
74 void *server_certificate_check_payload
;
76 /** Certificate check callback for the proxy */
77 git_transport_certificate_check_cb proxy_certificate_check_cb
;
78 void *proxy_certificate_check_payload
;
79 } git_http_client_options
;
82 * Create a new httpclient instance with the given options.
84 * @param out pointer to receive the new instance
85 * @param opts options to create the client with or NULL for defaults
87 extern int git_http_client_new(
88 git_http_client
**out
,
89 git_http_client_options
*opts
);
92 * Sends a request to the host specified by the request URL. If the
93 * method is POST, either the the content_length or the chunked flag must
94 * be specified. The body should be provided in subsequent calls to
95 * git_http_client_send_body.
97 * @param client the client to write the request to
98 * @param request the request to send
100 extern int git_http_client_send_request(
101 git_http_client
*client
,
102 git_http_request
*request
);
105 * After sending a request, there may already be a response to read --
106 * either because there was a non-continue response to an expect: continue
107 * request, or because the server pipelined a response to us before we even
108 * sent the request. Examine the state.
110 * @param client the client to examine
111 * @return true if there's already a response to read, false otherwise
113 extern bool git_http_client_has_response(git_http_client
*client
);
116 * Sends the given buffer to the remote as part of the request body. The
117 * request must have specified either a content_length or the chunked flag.
119 * @param client the client to write the request body to
120 * @param buffer the request body
121 * @param buffer_len number of bytes of the buffer to send
123 extern int git_http_client_send_body(
124 git_http_client
*client
,
129 * Reads the headers of a response to a request. This will consume the
130 * entirety of the headers of a response from the server. The body (if any)
131 * can be read by calling git_http_client_read_body. Callers must free
132 * the response with git_http_response_dispose.
134 * @param response pointer to the response object to fill
135 * @param client the client to read the response from
137 extern int git_http_client_read_response(
138 git_http_response
*response
,
139 git_http_client
*client
);
142 * Reads some or all of the body of a response. At most buffer_size (or
143 * INT_MAX) bytes will be read and placed into the buffer provided. The
144 * number of bytes read will be returned, or 0 to indicate that the end of
145 * the body has been read.
147 * @param client the client to read the response from
148 * @param buffer pointer to the buffer to fill
149 * @param buffer_size the maximum number of bytes to read
150 * @return the number of bytes read, 0 on end of body, or error code
152 extern int git_http_client_read_body(
153 git_http_client
*client
,
158 * Reads all of the (remainder of the) body of the response and ignores it.
159 * None of the data from the body will be returned to the caller.
161 * @param client the client to read the response from
162 * @return 0 or an error code
164 extern int git_http_client_skip_body(git_http_client
*client
);
167 * Examines the status code of the response to determine if it is a
168 * redirect of any type (eg, 301, 302, etc).
170 * @param response the response to inspect
171 * @return true if the response is a redirect, false otherwise
173 extern bool git_http_response_is_redirect(git_http_response
*response
);
176 * Frees any memory associated with the response.
178 * @param response the response to free
180 extern void git_http_response_dispose(git_http_response
*response
);
183 * Frees any memory associated with the client. If any sockets are open,
184 * they will be closed.
186 * @param client the client to free
188 extern void git_http_client_free(git_http_client
*client
);