From c4f502756ebe286fba3f9aa50f17c421d0eed9c0 Mon Sep 17 00:00:00 2001 From: Jan-Michael Brummer Date: Mon, 20 Mar 2023 06:15:54 -0400 Subject: Fix Libproxy documentation for non-dbus generation (#98) Co-authored-by: Jan-Michael Brummer --- src/libproxy/proxy-dbus.c | 96 ---------------------------------------------- src/libproxy/proxy.c | 17 -------- src/libproxy/proxy.h | 98 +++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 98 insertions(+), 113 deletions(-) diff --git a/src/libproxy/proxy-dbus.c b/src/libproxy/proxy-dbus.c index 6b594e3..57acbd9 100644 --- a/src/libproxy/proxy-dbus.c +++ b/src/libproxy/proxy-dbus.c @@ -28,11 +28,6 @@ struct _pxProxyFactory { GCancellable *cancellable; }; -/** - * SECTION:px-proxy - * @short_description: A convient helper for using proxy servers - */ - pxProxyFactory *px_proxy_factory_copy (pxProxyFactory *self); G_DEFINE_BOXED_TYPE (pxProxyFactory, @@ -40,24 +35,12 @@ G_DEFINE_BOXED_TYPE (pxProxyFactory, (GBoxedCopyFunc)px_proxy_factory_copy, (GFreeFunc)px_proxy_factory_new); - pxProxyFactory * px_proxy_factory_copy (pxProxyFactory *self) { return g_memdup2 (self, sizeof (pxProxyFactory)); } -/** - * px_proxy_factory_new: - * - * Creates a new `pxProxyFactory` instance. - * - * This instance should be kept around as long as possible as it contains - * cached data to increase performance. Memory usage should be minimal - * (cache is small) and the cache lifespan is handled automatically. - * - * Returns: The newly created `pxProxyFactory` - */ pxProxyFactory * px_proxy_factory_new (void) { @@ -93,70 +76,6 @@ px_proxy_factory_new (void) return self; } -/** - * px_proxy_factory_get_proxies: - * @self: a #pxProxyFactory - * @url: Get proxxies for specificed URL - * - * Get which proxies to use for the specified @URL. - * - * A %NULL-terminated array of proxy strings is returned. - * If the first proxy fails, the second should be tried, etc... - * Don't forget to free the strings/array when you are done. - * If an unrecoverable error occurs, this function returns %NULL. - * - * Regarding performance: this method always blocks and may be called - * in a separate thread (is thread-safe). In most cases, the time - * required to complete this function call is simply the time required - * to read the configuration (i.e. from gconf, kconfig, etc). - * - * In the case of PAC, if no valid PAC is found in the cache (i.e. - * configuration has changed, cache is invalid, etc), the PAC file is - * downloaded and inserted into the cache. This is the most expensive - * operation as the PAC is retrieved over the network. Once a PAC exists - * in the cache, it is merely a javascript invocation to evaluate the PAC. - * One should note that DNS can be called from within a PAC during - * javascript invocation. - * - * In the case of WPAD, WPAD is used to automatically locate a PAC on the - * network. Currently, we only use DNS for this, but other methods may - * be implemented in the future. Once the PAC is located, normal PAC - * performance (described above) applies. - * - * The format of the returned proxy strings are as follows: - * - * - http://[username:password@]proxy:port - * - * - socks://[username:password@]proxy:port - * - * - socks5://[username:password@]proxy:port - * - * - socks4://[username:password@]proxy:port - * - * - ://[username:password@]proxy:port - * - * - direct:// - * - * Please note that the username and password in the above URLs are optional - * and should be use to authenticate the connection if present. - * - * For SOCKS proxies, when the protocol version is specified (socks4:// or - * socks5://), it is expected that only this version is used. When only - * socks:// is set, the client MUST try SOCKS version 5 protocol and, on - * connection failure, fallback to SOCKS version 4. - * - * Other proxying protocols may exist. It is expected that the returned - * configuration scheme shall match the network service name of the - * proxy protocol or the service name of the protocol being proxied if the - * previous does not exist. As an example, on Mac OS X you can configure a - * RTSP streaming proxy. The expected returned configuration would be: - * - * - rtsp://[username:password@]proxy:port - * - * To free the returned value, call @px_proxy_factory_free_proxies. - * - * Returns: (transfer full): a list of proxies - */ char ** px_proxy_factory_get_proxies (pxProxyFactory *self, const char *url) @@ -209,27 +128,12 @@ px_proxy_factory_get_proxies (pxProxyFactory *self, return retval; } -/** - * px_proxy_factory_free_proxies - * @proxies: (array zero-terminated=1): a %NULL-terminated array of proxies - * - * Frees the proxy array returned by @px_proxy_factory_get_proxies when no - * longer used. - * - * @since 0.4.16 - */ void px_proxy_factory_free_proxies (char **proxies) { g_clear_pointer (&proxies, g_strfreev); } -/** - * px_proxy_factory_free: - * @self: a #pxProxyFactory - * - * Frees the `pxProxyFactory`. - */ void px_proxy_factory_free (pxProxyFactory *self) { diff --git a/src/libproxy/proxy.c b/src/libproxy/proxy.c index 278c0af..6cf7974 100644 --- a/src/libproxy/proxy.c +++ b/src/libproxy/proxy.c @@ -24,11 +24,6 @@ #include "px-manager.h" #include "proxy.h" -/** - * SECTION:px-proxy - * @short_description: A convient helper for using proxy servers - */ - struct _pxProxyFactory { PxManager *manager; }; @@ -40,12 +35,6 @@ G_DEFINE_BOXED_TYPE (pxProxyFactory, (GBoxedCopyFunc)px_proxy_factory_copy, (GFreeFunc)px_proxy_factory_new); -/** - * px_proxy_factory_new: - * Creates a new proxy factory. - * - * Returns: pointer to #px_proxy_factory - */ pxProxyFactory * px_proxy_factory_new (void) { @@ -82,12 +71,6 @@ px_proxy_factory_free_proxies (char **proxies) g_clear_pointer (&proxies, g_strfreev); } -/** - * px_proxy_factory_free: - * @self: a px_proxy_factory - * - * Free px_proxy_factory - */ void px_proxy_factory_free (pxProxyFactory *self) { diff --git a/src/libproxy/proxy.h b/src/libproxy/proxy.h index 50f9944..cf4fc34 100644 --- a/src/libproxy/proxy.h +++ b/src/libproxy/proxy.h @@ -28,15 +28,113 @@ extern "C" { #include +/** + * SECTION:px-proxy + * @short_description: A convient helper for using proxy servers + */ + typedef struct _pxProxyFactory pxProxyFactory; #define PX_TYPE_PROXY_FACTORY (px_proxy_factory_get_type ()) +/** + * px_proxy_factory_new: + * + * Creates a new `pxProxyFactory` instance. + * + * This instance should be kept around as long as possible as it contains + * cached data to increase performance. Memory usage should be minimal + * (cache is small) and the cache lifespan is handled automatically. + * + * Returns: The newly created `pxProxyFactory` + */ pxProxyFactory *px_proxy_factory_new (void); + GType px_proxy_factory_get_type (void) G_GNUC_CONST; +/** + * px_proxy_factory_get_proxies: + * @self: a #pxProxyFactory + * @url: Get proxxies for specificed URL + * + * Get which proxies to use for the specified @URL. + * + * A %NULL-terminated array of proxy strings is returned. + * If the first proxy fails, the second should be tried, etc... + * Don't forget to free the strings/array when you are done. + * If an unrecoverable error occurs, this function returns %NULL. + * + * Regarding performance: this method always blocks and may be called + * in a separate thread (is thread-safe). In most cases, the time + * required to complete this function call is simply the time required + * to read the configuration (i.e. from gconf, kconfig, etc). + * + * In the case of PAC, if no valid PAC is found in the cache (i.e. + * configuration has changed, cache is invalid, etc), the PAC file is + * downloaded and inserted into the cache. This is the most expensive + * operation as the PAC is retrieved over the network. Once a PAC exists + * in the cache, it is merely a javascript invocation to evaluate the PAC. + * One should note that DNS can be called from within a PAC during + * javascript invocation. + * + * In the case of WPAD, WPAD is used to automatically locate a PAC on the + * network. Currently, we only use DNS for this, but other methods may + * be implemented in the future. Once the PAC is located, normal PAC + * performance (described above) applies. + * + * The format of the returned proxy strings are as follows: + * + * - http://[username:password@]proxy:port + * + * - socks://[username:password@]proxy:port + * + * - socks5://[username:password@]proxy:port + * + * - socks4://[username:password@]proxy:port + * + * - ://[username:password@]proxy:port + * + * - direct:// + * + * Please note that the username and password in the above URLs are optional + * and should be use to authenticate the connection if present. + * + * For SOCKS proxies, when the protocol version is specified (socks4:// or + * socks5://), it is expected that only this version is used. When only + * socks:// is set, the client MUST try SOCKS version 5 protocol and, on + * connection failure, fallback to SOCKS version 4. + * + * Other proxying protocols may exist. It is expected that the returned + * configuration scheme shall match the network service name of the + * proxy protocol or the service name of the protocol being proxied if the + * previous does not exist. As an example, on Mac OS X you can configure a + * RTSP streaming proxy. The expected returned configuration would be: + * + * - rtsp://[username:password@]proxy:port + * + * To free the returned value, call @px_proxy_factory_free_proxies. + * + * Returns: (transfer full): a list of proxies + */ char **px_proxy_factory_get_proxies (pxProxyFactory *self, const char *url); + +/** + * px_proxy_factory_free_proxies + * @proxies: (array zero-terminated=1): a %NULL-terminated array of proxies + * + * Frees the proxy array returned by @px_proxy_factory_get_proxies when no + * longer used. + * + * @since 0.4.16 + */ void px_proxy_factory_free_proxies (char **proxies); + +/** + * px_proxy_factory_free: + * @self: a #pxProxyFactory + * + * Frees the `pxProxyFactory`. + */ void px_proxy_factory_free (pxProxyFactory *self); #ifdef __cplusplus -- cgit v1.2.1