diff options
author | Jan-Michael Brummer <jan.brummer@tabos.org> | 2023-03-07 15:21:02 +0100 |
---|---|---|
committer | Jan-Michael Brummer <jan.brummer@tabos.org> | 2023-03-27 16:31:58 +0200 |
commit | 1752685aa329e434d0410a8d865722c294efe137 (patch) | |
tree | 1bf2dc3d56a0612e1d1d3b3a40518636d32fa86f | |
parent | a8ec41a5f13593db3ca16dc0d64a1d6e40590e81 (diff) | |
download | libproxy-git-1752685aa329e434d0410a8d865722c294efe137.tar.gz |
Add samples (#64)
* Change Namespace to Libproxy
* Add samples
Fixes: https://github.com/janbrummer/libproxy2/issues/33
-rw-r--r-- | docs/build-howto.md | 123 | ||||
-rw-r--r-- | docs/meson.build | 5 | ||||
-rw-r--r-- | docs/perl.md | 21 | ||||
-rw-r--r-- | docs/px.toml.in | 5 | ||||
-rw-r--r-- | docs/python.md | 30 | ||||
-rw-r--r-- | docs/ruby.md | 20 | ||||
-rw-r--r-- | docs/vala.md | 32 | ||||
-rw-r--r-- | src/libproxy/meson.build | 2 | ||||
-rw-r--r-- | src/libproxy/proxy-dbus.c | 2 |
9 files changed, 113 insertions, 127 deletions
diff --git a/docs/build-howto.md b/docs/build-howto.md deleted file mode 100644 index 7ce0ef5..0000000 --- a/docs/build-howto.md +++ /dev/null @@ -1,123 +0,0 @@ -Title: Compiling with Libproxy -Slug: building - -# Compiling with Libproxy - -The current stable API provides a small synchronous function set which makes it easy to add it to existing application and libraries. - -The following example is written in C but can be translated as well to every other programming language thanks to gobject-introspection. Furthermore there are -several language samples provided in 'docs/samples' and also linked here in this main documentation. - -## Initialization - -First of all libproxy needs to be initialized. This is done with: - -``` -/** - * 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. - * - * @return A new pxProxyFactory instance or NULL on error - */ -pxProxyFactory *px_proxy_factory_new (void); -``` - -## Get proxy information - -Determining whether a proxy server is need to access a given url use `px_proxy_factory_get_proxies`: - -``` -/** - * px_proxy_factory_get_proxies: - * @self: a #pxProxyFactpry - * @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 - * - <procotol>://[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. - * - * @url The URL we are trying to reach - * @return A NULL-terminated array of proxy strings to use - */ -char **px_proxy_factory_get_proxies (pxProxyFactory *self, const char *url); -``` - -## Freeing proxy list - -Ensure unused proxy information is freed after user with `px_proxy_factory_free_proxies`: - -``` -/** - * px_proxy_factory_free_proxies - * @proxies: proxie array - * - * 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); -``` - -## Destruction - -To close and destroy the `pxProxyFactory` make use of: - -``` -/** - * px_proxy_factory_free: - * @self: a #pxProxyFactory - * - * Frees the pxProxyFactory instance when no longer used. - */ -void px_proxy_factory_free (pxProxyFactory *self); -``` diff --git a/docs/meson.build b/docs/meson.build index a468de9..556a13d 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -2,7 +2,10 @@ if get_option('docs') expand_content_md_files = [ 'configuration-logic.md', - 'build-howto.md', + 'perl.md', + 'python.md', + 'ruby.md', + 'vala.md', ] toml_data = configuration_data() diff --git a/docs/perl.md b/docs/perl.md new file mode 100644 index 0000000..eee6bbe --- /dev/null +++ b/docs/perl.md @@ -0,0 +1,21 @@ +Title: How to use libproxy in Perl +Slug: snippets + +# How to use libproxy in Perl + +``` +#!/usr/bin/perl +use warnings; +use Glib::Object::Introspection; +Glib::Object::Introspection->setup( + basename => 'Px', + version => '1.0', + package => 'Px'); + +my $pf = new Px::ProxyFactory; + +$proxies = $pf->get_proxies("https://github.com/libproxy/libproxy"); +foreach my $proxy (@$proxies) { + print $proxy."\n"; +} +``` diff --git a/docs/px.toml.in b/docs/px.toml.in index 1c91b0a..5bc08c9 100644 --- a/docs/px.toml.in +++ b/docs/px.toml.in @@ -62,7 +62,10 @@ file_format = "{filename}#L{line}" [extra] content_files = [ "configuration-logic.md", - "build-howto.md", + "perl.md", + "python.md", + "ruby.md", + "vala.md", ] content_images = [ diff --git a/docs/python.md b/docs/python.md new file mode 100644 index 0000000..8094e0b --- /dev/null +++ b/docs/python.md @@ -0,0 +1,30 @@ +Title: How to use libproxy in Python +Slug: snippets + +# How to use libproxy in Python + +``` +import gi +gi.require_version('Libproxy', '1.0') +from gi.repository import Libproxy +import requests + +url = 'https://github.com/libproxy/libproxy' + +pf = Libproxy.ProxyFactory() +proxies = pf.get_proxies(url) + +success = False +for proxy in proxies: + response = requests.get(url) #, proxies=proxies) + + if response.status_code == 200: + success = True + break + +if success: + print(f"The requested URL {url} could be retrieved using the current setup!") +else: + print(f"The requested URL {url} could *NOT* be retrieved using the current setup") +``` + diff --git a/docs/ruby.md b/docs/ruby.md new file mode 100644 index 0000000..ceddbd8 --- /dev/null +++ b/docs/ruby.md @@ -0,0 +1,20 @@ +Title: How to use libproxy in Ruby +Slug: snippets + +# How to use libproxy in Ruby + +``` +#!/usr/bin/ruby + +require 'gir_ffi' +GirFFI.setup :Libproxy + +pf = Libproxy::ProxyFactory.new() + +proxies = pf.get_proxies("https://github.com/libproxy/libproxy") +proxies.each do |proxy| + puts proxy +end + +pf.free() +``` diff --git a/docs/vala.md b/docs/vala.md new file mode 100644 index 0000000..b1332ac --- /dev/null +++ b/docs/vala.md @@ -0,0 +1,32 @@ +Title: How to use libproxy in Vala +Slug: snippets + +# How to use libproxy in Vala + + +## Makefile + +``` +all: sample + +sample: sample.vala + valac --pkg libproxy-1.0 sample.vala + +clean: + rm sample +``` + +## Source + +``` +using px; + +void main() { + var pf = new px.ProxyFactory(); + string[] proxies = pf.get_proxies("https://github.com/libproxy/libproxy"); + + foreach (string proxy in proxies) { + stdout.printf ("%s\n", proxy); + } +} +``` diff --git a/src/libproxy/meson.build b/src/libproxy/meson.build index e088f0c..8fdd880 100644 --- a/src/libproxy/meson.build +++ b/src/libproxy/meson.build @@ -72,7 +72,7 @@ libproxy_gir = gnome.generate_gir( libproxy_lib, sources: libproxy_headers + libproxy_sources, nsversion: api_version, - namespace: 'Px', + namespace: 'Libproxy', export_packages: package_api_name, symbol_prefix: 'px', identifier_prefix: 'px', diff --git a/src/libproxy/proxy-dbus.c b/src/libproxy/proxy-dbus.c index e9d935b..1587c73 100644 --- a/src/libproxy/proxy-dbus.c +++ b/src/libproxy/proxy-dbus.c @@ -197,7 +197,7 @@ px_proxy_factory_get_proxies (pxProxyFactory *self, /** * px_proxy_factory_free_proxies - * @proxies: proxy array + * @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. |