Data Structures | Typedefs | Enumerations
proxy.h File Reference
libpurple

Proxy API. More...

`#include <glib.h>`
`#include "eventloop.h"`
`#include "account.h"`

Go to the source code of this file.

## Data Structures
struct | PurpleProxyInfo
| Information on proxy settings. More...

## Typedefs
typedef struct _PurpleProxyConnectData | PurpleProxyConnectData
typedef void(* | PurpleProxyConnectFunction) (gpointer data, gint source, const gchar *error_message)

## Enumerations
enum | PurpleProxyType { PURPLE_PROXY_USE_GLOBAL = -1, PURPLE_PROXY_NONE = 0, PURPLE_PROXY_HTTP, PURPLE_PROXY_SOCKS4, PURPLE_PROXY_SOCKS5, PURPLE_PROXY_USE_ENVVAR, PURPLE_PROXY_TOR }
| A type of proxy connection. More...

## Functions
Proxy structure API
PurpleProxyInfo * | purple_proxy_info_new (void)
| Creates a proxy information structure. More...
void | purple_proxy_info_destroy (PurpleProxyInfo *info)
| Destroys a proxy information structure. More...
void | purple_proxy_info_set_type (PurpleProxyInfo *info, PurpleProxyType type)
| Sets the type of proxy. More...
void | purple_proxy_info_set_host (PurpleProxyInfo *info, const char *host)
| Sets the proxy host. More...
void | purple_proxy_info_set_port (PurpleProxyInfo *info, int port)
| Sets the proxy port. More...
void | purple_proxy_info_set_username (PurpleProxyInfo *info, const char *username)
| Sets the proxy username. More...
void | purple_proxy_info_set_password (PurpleProxyInfo *info, const char *password)
| Sets the proxy password. More...
PurpleProxyType | purple_proxy_info_get_type (const PurpleProxyInfo *info)
| Returns the proxy's type. More...
const char * | purple_proxy_info_get_host (const PurpleProxyInfo *info)
| Returns the proxy's host. More...
int | purple_proxy_info_get_port (const PurpleProxyInfo *info)
| Returns the proxy's port. More...
const char * | purple_proxy_info_get_username (const PurpleProxyInfo *info)
| Returns the proxy's username. More...
const char * | purple_proxy_info_get_password (const PurpleProxyInfo *info)
| Returns the proxy's password. More...
Global Proxy API
PurpleProxyInfo * | purple_global_proxy_get_info (void)
| Returns purple's global proxy information. More...
void | purple_global_proxy_set_info (PurpleProxyInfo *info)
| Set purple's global proxy information. More...
Proxy API
void * | purple_proxy_get_handle (void)
| Returns the proxy subsystem handle. More...
void | purple_proxy_init (void)
| Initializes the proxy subsystem.
void | purple_proxy_uninit (void)
| Uninitializes the proxy subsystem.
PurpleProxyInfo * | purple_proxy_get_setup (PurpleAccount *account)
| Returns configuration of a proxy. More...
PurpleProxyConnectData * | purple_proxy_connect (void *handle, PurpleAccount *account, const char *host, int port, PurpleProxyConnectFunction connect_cb, gpointer data)
| Makes a connection to the specified host and port. More...
PurpleProxyConnectData * | purple_proxy_connect_udp (void *handle, PurpleAccount *account, const char *host, int port, PurpleProxyConnectFunction connect_cb, gpointer data)
| Makes a connection to the specified host and port. More...
PurpleProxyConnectData * | purple_proxy_connect_socks5_account (void *handle, PurpleAccount *account, PurpleProxyInfo *gpi, const char *host, int port, PurpleProxyConnectFunction connect_cb, gpointer data)
| Makes a connection through a SOCKS5 proxy. More...
PurpleProxyConnectData * | purple_proxy_connect_socks5 (void *handle, PurpleProxyInfo *gpi, const char *host, int port, PurpleProxyConnectFunction connect_cb, gpointer data)
| Makes a connection through a SOCKS5 proxy. More...
void | purple_proxy_connect_cancel (PurpleProxyConnectData *connect_data)
| Cancel an in-progress connection attempt. More...
void | purple_proxy_connect_cancel_with_handle (void *handle)

## Detailed Description

Proxy API.

Definition in file proxy.h.

## Enumeration Type Documentation

## ◆ PurpleProxyType

enum PurpleProxyType

A type of proxy connection.

Enumerator
PURPLE_PROXY_USE_GLOBAL | Use the global proxy information.
PURPLE_PROXY_NONE | No proxy.
PURPLE_PROXY_HTTP | HTTP proxy.
PURPLE_PROXY_SOCKS4 | SOCKS 4 proxy.
PURPLE_PROXY_SOCKS5 | SOCKS 5 proxy.
PURPLE_PROXY_USE_ENVVAR | Use environmental settings.
PURPLE_PROXY_TOR | Use a Tor proxy (SOCKS 5 really)

Definition at line 35 of file proxy.h.

## Function Documentation

## ◆ purple_global_proxy_get_info()

PurpleProxyInfo* purple_global_proxy_get_info | ( | void |  | ) |

Returns purple's global proxy information.

Returns
  The global proxy information.

## ◆ purple_global_proxy_set_info()

void purple_global_proxy_set_info | ( | PurpleProxyInfo * | info | ) |

Set purple's global proxy information.

Parameters

  info | The proxy information.

Since
  2.6.0

## ◆ purple_proxy_connect()

PurpleProxyConnectData* purple_proxy_connect | ( | void * | handle,
|  | PurpleAccount * | account,
|  | const char * | host,
|  | int | port,
|  | PurpleProxyConnectFunction | connect_cb,
|  | gpointer | data
| ) |  |

Makes a connection to the specified host and port.

Note that this function name can be misleading–although it is called "proxy connect," it is used for establishing any outgoing TCP connection, whether through a proxy or not.

Parameters

  handle | A handle that should be associated with this connection attempt. The handle can be used to cancel the connection attempt using the purple_proxy_connect_cancel_with_handle() function.
  account | The account making the connection.
  host | The destination host.
  port | The destination port.
  connect_cb | The function to call when the connection is established. If the connection failed then fd will be -1 and error message will be set to something descriptive (hopefully).
  data | User-defined data.

Returns
  NULL if there was an error, or a reference to an opaque data structure that can be used to cancel the pending connection, if needed.

## ◆ purple_proxy_connect_cancel()

void purple_proxy_connect_cancel | ( | PurpleProxyConnectData * | connect_data | ) |

Cancel an in-progress connection attempt.

This should be called by the PRPL if the user disables an account while it is still performing the initial sign on. Or when establishing a file transfer, if we attempt to connect to a remote user but they are behind a firewall then the PRPL can cancel the connection attempt early rather than just letting the OS's TCP/IP stack time-out the connection.

## ◆ purple_proxy_connect_socks5()

PurpleProxyConnectData* purple_proxy_connect_socks5 | ( | void * | handle,
|  | PurpleProxyInfo * | gpi,
|  | const char * | host,
|  | int | port,
|  | PurpleProxyConnectFunction | connect_cb,
|  | gpointer | data
| ) |  |

Makes a connection through a SOCKS5 proxy.

Parameters

  handle | A handle that should be associated with this connection attempt. The handle can be used to cancel the connection attempt using the purple_proxy_connect_cancel_with_handle() function.
  gpi | The PurpleProxyInfo specifying the proxy settings
  host | The destination host.
  port | The destination port.
  connect_cb | The function to call when the connection is established. If the connection failed then fd will be -1 and error message will be set to something descriptive (hopefully).
  data | User-defined data.

Returns
  NULL if there was an error, or a reference to an opaque data structure that can be used to cancel the pending connection, if needed.

Deprecated:
  Use purple_proxy_connect_socks5_account instead

## ◆ purple_proxy_connect_socks5_account()

PurpleProxyConnectData* purple_proxy_connect_socks5_account | ( | void * | handle,
|  | PurpleAccount * | account,
|  | PurpleProxyInfo * | gpi,
|  | const char * | host,
|  | int | port,
|  | PurpleProxyConnectFunction | connect_cb,
|  | gpointer | data
| ) |  |

Makes a connection through a SOCKS5 proxy.

Note that if the account that is making the connection uses a proxy, this connection to a SOCKS5 proxy will be made through the account proxy.

Parameters

  handle | A handle that should be associated with this connection attempt. The handle can be used to cancel the connection attempt using the purple_proxy_connect_cancel_with_handle() function.
  account | The account making the connection.
  gpi | The PurpleProxyInfo specifying the proxy settings
  host | The destination host.
  port | The destination port.
  connect_cb | The function to call when the connection is established. If the connection failed then fd will be -1 and error message will be set to something descriptive (hopefully).
  data | User-defined data.

Returns
  NULL if there was an error, or a reference to an opaque data structure that can be used to cancel the pending connection, if needed.

## ◆ purple_proxy_connect_udp()

PurpleProxyConnectData* purple_proxy_connect_udp | ( | void * | handle,
|  | PurpleAccount * | account,
|  | const char * | host,
|  | int | port,
|  | PurpleProxyConnectFunction | connect_cb,
|  | gpointer | data
| ) |  |

Makes a connection to the specified host and port.

Note that this function name can be misleading–although it is called "proxy connect," it is used for establishing any outgoing UDP connection, whether through a proxy or not.

Parameters

  handle | A handle that should be associated with this connection attempt. The handle can be used to cancel the connection attempt using the purple_proxy_connect_cancel_with_handle() function.
  account | The account making the connection.
  host | The destination host.
  port | The destination port.
  connect_cb | The function to call when the connection is established. If the connection failed then fd will be -1 and error message will be set to something descriptive (hopefully).
  data | User-defined data.

Returns
  NULL if there was an error, or a reference to an opaque data structure that can be used to cancel the pending connection, if needed.

## ◆ purple_proxy_get_handle()

void* purple_proxy_get_handle | ( | void |  | ) |

Returns the proxy subsystem handle.

Returns
  The proxy subsystem handle.

## ◆ purple_proxy_get_setup()

PurpleProxyInfo* purple_proxy_get_setup | ( | PurpleAccount * | account | ) |

Returns configuration of a proxy.

Parameters

  account | The account for which the configuration is needed.

Returns
  The configuration of a proxy.

## ◆ purple_proxy_info_destroy()

void purple_proxy_info_destroy | ( | PurpleProxyInfo * | info | ) |

Destroys a proxy information structure.

Parameters

  info | The proxy information structure to destroy.

## ◆ purple_proxy_info_get_host()

const char* purple_proxy_info_get_host | ( | const PurpleProxyInfo * | info | ) |

Returns the proxy's host.

Parameters

  info | The proxy information.

Returns
  The host.

## ◆ purple_proxy_info_get_password()

const char* purple_proxy_info_get_password | ( | const PurpleProxyInfo * | info | ) |

Returns the proxy's password.

Parameters

  info | The proxy information.

Returns
  The password.

## ◆ purple_proxy_info_get_port()

int purple_proxy_info_get_port | ( | const PurpleProxyInfo * | info | ) |

Returns the proxy's port.

Parameters

  info | The proxy information.

Returns
  The port.

## ◆ purple_proxy_info_get_type()

PurpleProxyType purple_proxy_info_get_type | ( | const PurpleProxyInfo * | info | ) |

Returns the proxy's type.

Parameters

  info | The proxy information.

Returns
  The type.

## ◆ purple_proxy_info_get_username()

const char* purple_proxy_info_get_username | ( | const PurpleProxyInfo * | info | ) |

Returns the proxy's username.

Parameters

  info | The proxy information.

Returns
  The username.

## ◆ purple_proxy_info_new()

PurpleProxyInfo* purple_proxy_info_new | ( | void |  | ) |

Creates a proxy information structure.

Returns
  The proxy information structure.

## ◆ purple_proxy_info_set_host()

void purple_proxy_info_set_host | ( | PurpleProxyInfo * | info,
|  | const char * | host
| ) |  |

Sets the proxy host.

Parameters

  info | The proxy information.
  host | The host.

## ◆ purple_proxy_info_set_password()

void purple_proxy_info_set_password | ( | PurpleProxyInfo * | info,
|  | const char * | password
| ) |  |

Sets the proxy password.

Parameters

  info | The proxy information.
  password | The password.

## ◆ purple_proxy_info_set_port()

void purple_proxy_info_set_port | ( | PurpleProxyInfo * | info,
|  | int | port
| ) |  |

Sets the proxy port.

Parameters

  info | The proxy information.
  port | The port.

## ◆ purple_proxy_info_set_type()

void purple_proxy_info_set_type | ( | PurpleProxyInfo * | info,
|  | PurpleProxyType | type
| ) |  |

Sets the type of proxy.

Parameters

  info | The proxy information.
  type | The proxy type.

## ◆ purple_proxy_info_set_username()

void purple_proxy_info_set_username | ( | PurpleProxyInfo * | info,
|  | const char * | username
| ) |  |

Sets the proxy username.

Parameters

  info | The proxy information.
  username | The username.