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 #ifndef INCLUDE_sys_git_stream_h__ 8 #define INCLUDE_sys_git_stream_h__ 9 10 #include "git2/common.h" 11 #include "git2/types.h" 12 #include "git2/proxy.h" 13 14 GIT_BEGIN_DECL 15 16 #define GIT_STREAM_VERSION 1 17 18 /** 19 * Every stream must have this struct as its first element, so the 20 * API can talk to it. You'd define your stream as 21 * 22 * struct my_stream { 23 * git_stream parent; 24 * ... 25 * } 26 * 27 * and fill the functions 28 */ 29 typedef struct git_stream { 30 int version; 31 32 int encrypted; 33 int proxy_support; 34 int GIT_CALLBACK(connect)(struct git_stream *); 35 int GIT_CALLBACK(certificate)(git_cert **, struct git_stream *); 36 int GIT_CALLBACK(set_proxy)(struct git_stream *, const git_proxy_options *proxy_opts); 37 ssize_t GIT_CALLBACK(read)(struct git_stream *, void *, size_t); 38 ssize_t GIT_CALLBACK(write)(struct git_stream *, const char *, size_t, int); 39 int GIT_CALLBACK(close)(struct git_stream *); 40 void GIT_CALLBACK(free)(struct git_stream *); 41 } git_stream; 42 43 typedef struct { 44 /** The `version` field should be set to `GIT_STREAM_VERSION`. */ 45 int version; 46 47 /** 48 * Called to create a new connection to a given host. 49 * 50 * @param out The created stream 51 * @param host The hostname to connect to; may be a hostname or 52 * IP address 53 * @param port The port to connect to; may be a port number or 54 * service name 55 * @return 0 or an error code 56 */ 57 int GIT_CALLBACK(init)(git_stream **out, const char *host, const char *port); 58 59 /** 60 * Called to create a new connection on top of the given stream. If 61 * this is a TLS stream, then this function may be used to proxy a 62 * TLS stream over an HTTP CONNECT session. If this is unset, then 63 * HTTP CONNECT proxies will not be supported. 64 * 65 * @param out The created stream 66 * @param in An existing stream to add TLS to 67 * @param host The hostname that the stream is connected to, 68 * for certificate validation 69 * @return 0 or an error code 70 */ 71 int GIT_CALLBACK(wrap)(git_stream **out, git_stream *in, const char *host); 72 } git_stream_registration; 73 74 /** 75 * The type of stream to register. 76 */ 77 typedef enum { 78 /** A standard (non-TLS) socket. */ 79 GIT_STREAM_STANDARD = 1, 80 81 /** A TLS-encrypted socket. */ 82 GIT_STREAM_TLS = 2, 83 } git_stream_t; 84 85 /** 86 * Register stream constructors for the library to use 87 * 88 * If a registration structure is already set, it will be overwritten. 89 * Pass `NULL` in order to deregister the current constructor and return 90 * to the system defaults. 91 * 92 * The type parameter may be a bitwise AND of types. 93 * 94 * @param type the type or types of stream to register 95 * @param registration the registration data 96 * @return 0 or an error code 97 */ 98 GIT_EXTERN(int) git_stream_register( 99 git_stream_t type, git_stream_registration *registration); 100 101 #ifndef GIT_DEPRECATE_HARD 102 103 /** @name Deprecated TLS Stream Registration Functions 104 * 105 * These functions are retained for backward compatibility. The newer 106 * versions of these values should be preferred in all new code. 107 * 108 * There is no plan to remove these backward compatibility values at 109 * this time. 110 */ 111 /**@{*/ 112 113 /** 114 * @deprecated Provide a git_stream_registration to git_stream_register 115 * @see git_stream_registration 116 */ 117 typedef int GIT_CALLBACK(git_stream_cb)(git_stream **out, const char *host, const char *port); 118 119 /** 120 * Register a TLS stream constructor for the library to use. This stream 121 * will not support HTTP CONNECT proxies. This internally calls 122 * `git_stream_register` and is preserved for backward compatibility. 123 * 124 * This function is deprecated, but there is no plan to remove this 125 * function at this time. 126 * 127 * @deprecated Provide a git_stream_registration to git_stream_register 128 * @see git_stream_register 129 */ 130 GIT_EXTERN(int) git_stream_register_tls(git_stream_cb ctor); 131 132 /**@}*/ 133 134 #endif 135 136 GIT_END_DECL 137 138 #endif 139
