diff options
author | Etienne Samson <samson.etienne@gmail.com> | 2019-01-15 13:35:41 +0100 |
---|---|---|
committer | Etienne Samson <samson.etienne@gmail.com> | 2019-01-28 13:05:52 +0100 |
commit | f6412c26c158161c5887ceb7e5ce86c2ad62499e (patch) | |
tree | d62753031218e4a1034c1f5885f4be1150d9f98a | |
parent | 2964fed0c5dfeb3b1349ed354f57a3e10ac2a631 (diff) | |
download | libgit2-f6412c26c158161c5887ceb7e5ce86c2ad62499e.tar.gz |
transport: enhance documentation
-rw-r--r-- | include/git2/sys/transport.h | 145 |
1 files changed, 88 insertions, 57 deletions
diff --git a/include/git2/sys/transport.h b/include/git2/sys/transport.h index 92cb32b17..bba8feafe 100644 --- a/include/git2/sys/transport.h +++ b/include/git2/sys/transport.h @@ -33,8 +33,9 @@ typedef enum { } git_transport_flags_t; struct git_transport { - unsigned int version; - /* Set progress and error callbacks */ + unsigned int version; /**< The struct version */ + + /** Set progress and error callbacks */ int GIT_CALLBACK(set_callbacks)( git_transport *transport, git_transport_message_cb progress_cb, @@ -42,13 +43,15 @@ struct git_transport { git_transport_certificate_check_cb certificate_check_cb, void *payload); - /* Set custom headers for HTTP requests */ + /** Set custom headers for HTTP requests */ int GIT_CALLBACK(set_custom_headers)( git_transport *transport, const git_strarray *custom_headers); - /* Connect the transport to the remote repository, using the given - * direction. */ + /** + * Connect the transport to the remote repository, using the given + * direction. + */ int GIT_CALLBACK(connect)( git_transport *transport, const char *url, @@ -58,29 +61,40 @@ struct git_transport { int direction, int flags); - /* This function may be called after a successful call to - * connect(). The array returned is owned by the transport and - * is guaranteed until the next call of a transport function. */ + /** + * Get the list of available references in the remote repository. + * + * This function may be called after a successful call to + * `connect()`. The array returned is owned by the transport and + * must be kept valid until the next call to one of its functions. + */ int GIT_CALLBACK(ls)( const git_remote_head ***out, size_t *size, git_transport *transport); - /* Executes the push whose context is in the git_push object. */ + /** Executes the push whose context is in the git_push object. */ int GIT_CALLBACK(push)(git_transport *transport, git_push *push, const git_remote_callbacks *callbacks); - /* This function may be called after a successful call to connect(), when - * the direction is FETCH. The function performs a negotiation to calculate - * the wants list for the fetch. */ + /** + * Negotiate a fetch with the remote repository. + * + * This function may be called after a successful call to `connect()`, + * when the direction is GIT_DIRECTION_FETCH. The function performs a + * negotiation to calculate the `wants` list for the fetch. + */ int GIT_CALLBACK(negotiate_fetch)( git_transport *transport, git_repository *repo, const git_remote_head * const *refs, size_t count); - /* This function may be called after a successful call to negotiate_fetch(), - * when the direction is FETCH. This function retrieves the pack file for - * the fetch from the remote end. */ + /** + * Start downloading the packfile from the remote repository. + * + * This function may be called after a successful call to + * negotiate_fetch(), when the direction is GIT_DIRECTION_FETCH. + */ int GIT_CALLBACK(download_pack)( git_transport *transport, git_repository *repo, @@ -88,20 +102,24 @@ struct git_transport { git_transfer_progress_cb progress_cb, void *progress_payload); - /* Checks to see if the transport is connected */ + /** Checks to see if the transport is connected */ int GIT_CALLBACK(is_connected)(git_transport *transport); - /* Reads the flags value previously passed into connect() */ + /** Reads the flags value previously passed into connect() */ int GIT_CALLBACK(read_flags)(git_transport *transport, int *flags); - /* Cancels any outstanding transport operation */ + /** Cancels any outstanding transport operation */ void GIT_CALLBACK(cancel)(git_transport *transport); - /* This function is the reverse of connect() -- it terminates the - * connection to the remote end. */ + /** + * Close the connection to the remote repository. + * + * This function is the reverse of connect() -- it terminates the + * connection to the remote end. + */ int GIT_CALLBACK(close)(git_transport *transport); - /* Frees/destructs the git_transport object. */ + /** Frees/destructs the git_transport object. */ void GIT_CALLBACK(free)(git_transport *transport); }; @@ -167,10 +185,13 @@ GIT_EXTERN(int) git_transport_register( void *param); /** - * * Unregister a custom transport definition which was previously registered * with git_transport_register. * + * The caller is responsible for synchronizing calls to git_transport_register + * and git_transport_unregister with other calls to the library that + * instantiate transports. + * * @param prefix From the previous call to git_transport_register * @return 0 or an error code */ @@ -262,20 +283,7 @@ GIT_EXTERN(int) git_transport_smart_proxy_options(git_proxy_options *out, git_tr *** Begin interface for subtransports for the smart transport *** */ -/* The smart transport knows how to speak the git protocol, but it has no - * knowledge of how to establish a connection between it and another endpoint, - * or how to move data back and forth. For this, a subtransport interface is - * declared, and the smart transport delegates this work to the subtransports. - * Three subtransports are implemented: git, http, and winhttp. (The http and - * winhttp transports each implement both http and https.) */ - -/* Subtransports can either be RPC = 0 (persistent connection) or RPC = 1 - * (request/response). The smart transport handles the differences in its own - * logic. The git subtransport is RPC = 0, while http and winhttp are both - * RPC = 1. */ - -/* Actions that the smart transport can ask - * a subtransport to perform */ +/** Actions that the smart transport can ask a subtransport to perform */ typedef enum { GIT_SERVICE_UPLOADPACK_LS = 1, GIT_SERVICE_UPLOADPACK = 2, @@ -286,58 +294,81 @@ typedef enum { typedef struct git_smart_subtransport git_smart_subtransport; typedef struct git_smart_subtransport_stream git_smart_subtransport_stream; -/* A stream used by the smart transport to read and write data +/** + * A stream used by the smart transport to read and write data * from a subtransport */ struct git_smart_subtransport_stream { - /* The owning subtransport */ + /** The owning subtransport */ git_smart_subtransport *subtransport; + /** Read available data from the stream */ int GIT_CALLBACK(read)( git_smart_subtransport_stream *stream, char *buffer, size_t buf_size, size_t *bytes_read); + /** Write data to the stream */ int GIT_CALLBACK(write)( git_smart_subtransport_stream *stream, const char *buffer, size_t len); + /** Free the stream */ void GIT_CALLBACK(free)( git_smart_subtransport_stream *stream); }; -/* An implementation of a subtransport which carries data for the +/** + * An implementation of a subtransport which carries data for the * smart transport */ struct git_smart_subtransport { + /** + * Setup a subtransport stream for the requested action. + */ int GIT_CALLBACK(action)( git_smart_subtransport_stream **out, git_smart_subtransport *transport, const char *url, git_smart_service_t action); - /* Subtransports are guaranteed a call to close() between + /** + * Close the subtransport. + * + * Subtransports are guaranteed a call to close() between * calls to action(), except for the following two "natural" progressions - * of actions against a constant URL. + * of actions against a constant URL: * - * 1. UPLOADPACK_LS -> UPLOADPACK - * 2. RECEIVEPACK_LS -> RECEIVEPACK */ + * - UPLOADPACK_LS -> UPLOADPACK + * - RECEIVEPACK_LS -> RECEIVEPACK + */ int GIT_CALLBACK(close)(git_smart_subtransport *transport); + /** Free the subtransport */ void GIT_CALLBACK(free)(git_smart_subtransport *transport); }; -/* A function which creates a new subtransport for the smart transport */ +/** A function which creates a new subtransport for the smart transport */ typedef int GIT_CALLBACK(git_smart_subtransport_cb)( git_smart_subtransport **out, - git_transport* owner, - void* param); + git_transport *owner, + void *param); /** * Definition for a "subtransport" * - * This is used to let the smart protocol code know about the protocol - * which you are implementing. + * The smart transport knows how to speak the git protocol, but it has no + * knowledge of how to establish a connection between it and another endpoint, + * or how to move data back and forth. For this, a subtransport interface is + * declared, and the smart transport delegates this work to the subtransports. + * + * Three subtransports are provided by libgit2: git, http, and winhttp. + * The http and winhttp transports each implement both http and https. + * + * Subtransports can either be RPC = 0 (persistent connection) or RPC = 1 + * (request/response). The smart transport handles the differences in its own + * logic. The git subtransport is RPC = 0, while http and winhttp are both + * RPC = 1. */ typedef struct git_smart_subtransport_definition { /** The function to use to create the git_smart_subtransport */ @@ -349,17 +380,17 @@ typedef struct git_smart_subtransport_definition { */ unsigned rpc; - /** Param of the callback - */ - void* param; + /** User-specified parameter passed to the callback */ + void *param; } git_smart_subtransport_definition; /* Smart transport subtransports that come with libgit2 */ /** - * Create an instance of the http subtransport. This subtransport - * also supports https. On Win32, this subtransport may be implemented - * using the WinHTTP library. + * Create an instance of the http subtransport. + * + * This subtransport also supports https. On Win32, this subtransport may be + * implemented using the WinHTTP library. * * @param out The newly created subtransport * @param owner The smart transport to own this subtransport @@ -367,7 +398,7 @@ typedef struct git_smart_subtransport_definition { */ GIT_EXTERN(int) git_smart_subtransport_http( git_smart_subtransport **out, - git_transport* owner, + git_transport *owner, void *param); /** @@ -379,7 +410,7 @@ GIT_EXTERN(int) git_smart_subtransport_http( */ GIT_EXTERN(int) git_smart_subtransport_git( git_smart_subtransport **out, - git_transport* owner, + git_transport *owner, void *param); /** @@ -391,7 +422,7 @@ GIT_EXTERN(int) git_smart_subtransport_git( */ GIT_EXTERN(int) git_smart_subtransport_ssh( git_smart_subtransport **out, - git_transport* owner, + git_transport *owner, void *param); /** @} */ |