1.

Functions that are called by AdvTor if the plugin exports the

m

1.1. int __stdcall AdvTor_InitPlugin(HANDLE plugin_instance,DWORD versio

n,char *plugin_description,void *function_table);
plugin_instance = a handler for current plugin instance that is required
by some function calls
version = current version of AdvTor
LOWORD(version) = minor version
HIWORD(version) = major version
plugin_description = a buffer of 256 bytes that receives a string specif
ying plugin description (UTF-8)
function_table = a pointer to an array of functions that can be called b
y this plugin, for more information see plugins.h
Return values:
0 = initialization failed and the plugin cannot be loaded at thi
s time
1 = initialization was successfull
This is the first function that is called by AdvTor after loading a plug
in DLL and it is the only function that is required to load it. If the function
is not exported, AdvTor will not load this plugin and will not show it in plugin
list.

1.2. int __stdcall AdvTor_UnloadPlugin(int reason);

reason = an integer which can have one of the following values:
PLUGIN_UNLOAD_ON_DEMAND = the user clicked the "Unload" button
return values:
0 = the plugin cannot be unloaded at this time;
the user will see a MessageBox with a warning and he can choose to unload it any
way (in this case, AdvTor_UnloadPlugin will be called again with PLUGIN_UNLOAD_M
UST_UNLOAD) or to cancel unloading (in this case, AdvTor_UnloadPlugin will be ca
lled again with PLUGIN_UNLOAD_CANCEL)
1 = the plugin can be unloaded and FreeLibrary w
ill be called
PLUGIN_UNLOAD_RELOAD = the user clicked "Reload"
return values:
0 = the plugin cannot be reloaded at this time
1 = the plugin can be unloaded and FreeLibrary w
ill be called
-1 = the plugin cannot be unloaded, but AdvTor_I
nitPlugin will be called again and AdvTor_GetConfigurationWindow if available
PLUGIN_UNLOAD_AT_EXIT = AdvTor is about to exit
return values:
0 = the plugin cannot be unloaded at this time;
the user will see a MessageBox with a warning and he can choose to unload it any
way (in this case, AdvTor_UnloadPlugin will be called again with PLUGIN_UNLOAD_M
UST_UNLOAD) or to cancel unloading (in this case, AdvTor_UnloadPlugin will be ca
lled again with PLUGIN_UNLOAD_CANCEL)
1 = the plugin can be unloaded and FreeLibrary w
ill be called
PLUGIN_UNLOAD_MUST_UNLOAD = the user selected the option to unlo
ad the plugin anyway and FreeLibrary will be called
 no return values
PLUGIN_UNLOAD_CANCEL = unloading this plugin was canceled by use
r
no return values
This function is called before unloading the library or when the user ca
ncels unloading this plugin.

1.3. HWND __stdcall AdvTor_GetConfigurationWindow(HWND hParent);

hParent = window handle for AdvTor main window
Return values:
- a handle of a child window that can be added as a separate Adv
Tor page
If this function is exported, AdvTor will add a new option for this plug
in's window and will call it to get a window handle that can be shown as a separ
ate page with configuration options related to this plugin. This function is onl
y called when the user clicks on the option related to this plugin to see the op
tions for the first time after the plugin was (re)initialized. The size and visi
bility of this window are controlled by AdvTor. The plugin must not create the c
onfiguration window before this function is called. The plugin must destroy this
window when the plugin will be unloaded. If AdvTor_UnloadPlugin is not exported
, this window will be destroyed before calling FreeLibrary to unload the plugin.
The following dialog template can be used:
ConfigDialog DIALOGEX MOVEABLE 84,0,288,252,0
STYLE WS_CHILDWINDOW | WS_VISIBLE | WS_CLIPSIBLINGS | WS_CLIPCHI
LDREN | DS_CONTROL | DS_SETFONT | DS_3DLOOK | DS_NOFAILCREATE | WS_CHILD
EXSTYLE WS_EX_CONTROLPARENT
FONT 8,"Arial",700,0
BEGIN
END

1.3.1. resize_info_t* __stdcall ResizeConfigurationWindow(RECT newSize)

;
newSize = a rectangle that has x-coordinate (newSize.left), y-coordinate
(newSize.top), new width (newSize.right) and new height (newSize.bottom) for co
nfiguration window
Return values:
- an array of resize_info_t structures that will be used to resi
ze or move dialog items to fit the new window dimensions; the last structure mus
t have ctrlId=0
- NULL if the plugin handles WM_SIZE events
If this function is exported, it is called before the configuration wind
ow is resized. Using -1 for for the first reference.left value will determine Ad
vTor to initialize reference rectangles using flags and current values for posit
ions and dimensions of dialog controls. Flags are defined in plugins.h.
If the first item has a control ID of -1, refWidthControl is the minimum
width and refHeightControl is the minimum height before enabling scroll bars an
d scrolling; if AdvOR should handle scroll bars and scrolling, the messages WM_H
SCROLL and WM_VSCROLL should be forwarded to the AdvOR main window as WM_USER+12
and WM_USER+13, having wParam unchanged and lParam is the window handle for thi
s plugin's configuration window.
 1.4. int __stdcall AdvTor_RegisterNewConnection(DWORD connection_id,int
connection_type,char *address,LPARAM *lParam);
connection_id = unique identifier for this connection
connection_type = connection type, as defined in plugins.h
address = remote address, can be NULL if no socket is associated with th
is connection or if the socket is not connected
lParam = a pointer to a 32-bit value that can be associated by this plug
in to this connection, or NULL if all available parameters are already used by o
ther plugins; this value is not changed by AdvTor
Return values:
0 = close this connection; the function that needs this connecti
on will fail whatever it is trying to do
1 = register this connection; other plugins can disallow registe
ring this connection

1.5. int __stdcall AdvTor_UnregisterConnection(DWORD connection_id,int c

onnection_type,char *address,LPARAM *lParam);
connection_id = unique identifier for this connection
connection_type = connection type, as defined in plugins.h
address = remote address, can be NULL if no socket is associated with th
is connection or if the socket is not connected
lParam = a pointer to a 32-bit value that can be associated by this plug
in to this connection, or NULL if all available parameters are already used by o
ther plugins; this value is not changed by AdvTor
Return values:
0 = don't close this connection; AdvTor_UnregisterConnection wil
l be called again for this connection
1 = close and unregister this connection

1.6. int __stdcall AdvTor_HandleRead(DWORD connection_id,int connection_

type,int connection_state,char *address,char *buffer_in,int *data_size,int max_d
ata_size,LPARAM *lParam);
connection_id = unique identifier for this connection
connection_type = connection type, as defined in plugins.h
connection_state = current state for this connection, as defined in plug
ins.h
address = remote address
buffer_in = a buffer that has data that was read from a socket or that w
as written by other plugins
data_size = a pointer to the number of bytes that were written to buffer
_in
max_data_size = maximum number of bytes that can be written to buffer_in
lParam = a pointer to a 32-bit value that can be associated by this plug
in to this connection, or NULL if all available parameters are already used by o
ther plugins; this value is not changed by AdvTor
Return values:
-1 = there was an error, this connection must be closed
 0 = call this function again to get more data
1 = continue processing this buffer
If the plugin changes the contents of buffer_in, it must also update dat
a_size. If other plugins already cleared buffer_in, or when 0 was returned from
previous call, data_size is 0 and max_data_size has the maximum number of bytes
that can be written to buffer_in.

1.7. int __stdcall AdvTor_HandleWrite(DWORD connection_id,int connection

_type,int connection_state,char *address,char *buffer_out,int *data_size,int max
_data_size,LPARAM *lParam);
connection_id = unique identifier for this connection
connection_type = connection type, as defined in plugins.h
connection_state = current state for this connection, as defined in plug
ins.h
address = remote address
buffer_out = a buffer that has the data that needs to be sent
data_size = a pointer to the number of bytes that were written to buffer
_out
max_data_size = maximum number of bytes that can be written to buffer_ou
t
lParam = a pointer to a 32-bit value that can be associated by this plug
in to this connection, or NULL if all available parameters are already used by o
ther plugins; this value is not changed by AdvTor
Return values:
-1 = there was an error, this connection must be closed
0 = call this function again to get more data
1 = continue processing this buffer
If the plugin changes the contents of buffer_out, it must also update da
ta_size. If other plugins already cleared buffer_out, or when 0 was returned fro
m previous call, data_size is 0 and max_data_size has the maximum number of byte
s that can be written to buffer_out.

1.8. int __stdcall AdvTor_TranslateAddress(DWORD connection_id,const cha

r *original_address,char *translated_address,LPARAM *lParam,BOOL is_error);
connection_id = unique identifier for the connection that is about to co
nnect to this address or 0 if the address is not associated with an existing con
nection
original_address = the address that was sent by a client or by AdvTor.dl
l
translated_address = final address that will be used by AdvTor with OR c
onnections; can point to original_address
lParam = a pointer to a 32-bit value that can be associated by this plug
in to this connection, or NULL if all available parameters are already used by o
ther plugins or connection_id is 0
is_error = a resolve request has failed for original_address
Return values:
0 = this address was banned by plugin
1 = continue processing this request
This function is called after a socks connection request was received fr
om a client, to allow plugins to re-map a requested address.

1.9. void __stdcall AdvTor_ChangeIdentity(DWORD new_IP,char *new_country

,long time_delta);
new_IP = new exit IP for all connections; 0.0.0.0 = random IP; 127.0.0.1
= no exit
new_country = a 2-letter country identifier or NULL if the exit will be
selected from a random country
time_delta = number of seconds that is added to current local time when
the option to use fake local time is enabled
This function is called every time the user selects a new exit for all c
onnections or when the "New identity" button is clicked.

1.10. void __stdcall AdvTor_Start(BOOL started);

started = a boolean value, 0 if entering hibernation, 1 if hibernation w
as canceled.
This function is called when hibernation status changes. When entering h
ibernation, all circuits are destroyed and all connections are closed. When hibe
rnation is canceled, AdvTor may not immediately start building circuits if predi
cted circuits are disabled.

1.11. void __stdcall AdvTor_RouterChanged(DWORD ip,unsigned char *identi

ty_hash,int changed);
ip = IP address of the router that was updated
identity_hash = identity digest of the router, of size DIGEST_LEN
changed = information about what was changed; can have one of the follow
ing values:
0 = a router was removed
1 = a router was added
2 = a router was updated
3 = the routerlist was refreshed
This function is called for each router that was changed when updating n
etwork status. If ip is 0, network status information was replaced.

1.12. BOOL HiddenService_NotifyService(int notification_code,char *onion

_address,int virtual_port,DWORD client_id,LPARAM *lParam);
notification_code = can have one of the following values:
HIDDENSERVICE_REGISTER_SERVICE
Return values:
0 = do not register this service
1 = register this service and publish hidden ser
vice information
HIDDENSERVICE_UNREGISTER_SERVICE
Return values: none
HIDDENSERVICE_REGISTER_CLIENT
 Return values:
0 = disconnect this client
1 = continue processing data from this client
HIDDENSERVICE_UNREGISTER_CLIENT
Return values: none
onion_address = a null-terminated string that has the address for the hi
dden service
virtual_port = a virtual port associated with this hidden service that c
an be used by clients
client_id = a unique identifier for a client connection or 0 if this par
ameter is not used
lParam = a pointer to a 32-bit value that can be associated by this plug
in to a client connection, or NULL if this parameter is not used or all availabl
e parameters are already used by other plugins; this value is not changed by Adv
Tor
This function is called to notify the plugin about interesting events re
lated to its hidden services.

1.13. BOOL HiddenService_HandleRead(char *onion_address,DWORD client_id,

char *buffer,int buffer_size,LPARAM *lParam);
onion_address = a null-terminated string that has the address for the hi
dden service
client_id = a unique identifier for a client connection
buffer = a buffer that has incoming data
buffer_size = the number of bytes that were received
lParam = a pointer to a 32-bit value that can be associated by this plug
in to this client connection, or NULL if all available parameters are already us
ed by other plugins; this value is not changed by AdvTor
Return values:
0 = disconnect this client
1 = continue processing data from this client
This function is called every time a hidden service provided by this plu
gin receives data from a client.

1.14. void __stdcall AdvTor_InterceptProcess(DWORD pid,BOOL intercept);

pid = identifier of a process that is intercepted or released
intercept = true if the process is intercepted, false if the process is
released
This function is called every time a new process is intercepted or an in
tercepted process is released.

1.15. void __stdcall AdvTor_LanguageChange(char *language_name);

language_name = the name of the language that was selected
This function is called every time a new language is selected from the S
ystem dialog.
 2. Functions that can be called by plugins

2.1. void __stdcall log(int severity,char *message);

severity = a priority code, 0 is the most important; severity codes are
defined in plugins.h
message = a NULL-terminated UTF-8 encoded string containg a message
This function outputs a message to debug window and/or saves it to log.

2.2. BOOL __stdcall tor_is_started(void);

This function returns true if TOR is started and false if TOR is hiberna
ting.

2.3. int __stdcall get_connection_count(void);

This function returns the number of registered connections.

2.4. int __stdcall get_connections(HANDLE hPlugin,connection_info_t *buf

fer,int connection_count);
hPlugin = a handler for current plugin instance given by AdvTor_InitPlug
in()
buffer = a pointer to an array of connection_info_t structures that will
be filled by this function
connection_count = maximum number of connection_info_t structures that c
an be written to this buffer
Return values:
- the number of connection_info_t structures written to buffer
This function returns an array of connection_info_t structures filled wi
th information about existing connections. To get the total number of connection
s use get_connection_count().

2.5. BOOL __stdcall close_connection(DWORD connection_id);

connection_id = unique identifier for an existing connection or for a hi
dden service client
This function closes an existing connection. If no connection having spe
cified connection_id was found, this function returns 0;

2.6. int __stdcall connection_read(DWORD connection_id);

 connection_id = unique identifier for an existing connection
Return values:
-1 = no connection was found having requested connection_id
0 = there was an error, no data can be processed at this time
This function causes an AdvTor_HandleRead event for all plugins.

2.7. int __stdcall connection_write(DWORD connection_id);

connection_id = unique identifier for an existing connection
Return values:
-1 = no connection was found having requested connection_id
0 = there was an error, no data can be processed at this time
This function causes an AdvTor_HandleWrite event for all plugins.

2.8. const char* __stdcall get_socks_address(DWORD connection_id,BOOL or

iginal_address);
connection_id = unique identifier for an existing connection
original_address = if this value is true, the function returns the origi
nal proxy request sent by the client that uses this connection; if this value is
false, the function returns a rewritten/remapped/resolved address that may be s
ent to OR network
This function retrieves a pointer to the address that is used by an edge
connection.

2.9. BOOL __stdcall set_socks_address(HANDLE plugin_instance,DWORD conne

ction_id,char *original_address,int command);
plugin_instance = the handler for current plugin instance that was retur
ned by AdvTor_InitPlugin()
connection_id = unique identifier for an existing connection
original_address = the new address that will be used for this connection
command = socks request, can be one of the following:
SOCKS_COMMAND_CONNECT - open a connection to original_
address
SOCKS_COMMAND_RESOLVE - resolve a hostname to an IP
SOCKS_COMMAND_RESOLVE_PTR - turn an IP into a hostname
Return values:
0 = no circuits can handle original address or the address is ba
nned
1 = the address was changed and the connection was re-attached t
o a new circuit
This function changes original_address of an existing connection and (re
)attaches the connection to a circuit that can handle original_address.
 2.10. DWORD __stdcall get_connecting_process(DWORD connection_id)
connection_id = unique identifier for an existing connection
Return values:
- identifier of the process that created this connection or 0 if
no PID is associated with it
This function returns the PID of the process that connected (or was redi
rected) to AdvTor's proxy port.

2.11. int __stdcall get_process_name(DWORD pid,char *buffer)

pid = identifier of a process
buffer = a buffer that receives the name of the module that created that
process
Return values:
- the number of bytes that were written to buffer including the
null terminator.
This function returns the name of the executable file that created a pro
cess.

2.12. int __stdcall translate_address(HANDLE plugin_instance,char *origi

nal_address,char *translated_address);
plugin_instance = the handler for current plugin instance that was retur
ned by AdvTor_InitPlugin()
original_address = the address that needs to be translated
translated_address = final address
Return values:
- the number of bytes that were written to translated_address in
cluding the null terminator.
This function searches address maps and calls all plugins to translate o
riginal_address.

2.13. void __stdcall map_address(HANDLE plugin_instance,char *address, c

har *new_address);
plugin_instance = the handler for current plugin instance that was retur
ned by AdvTor_InitPlugin()
address = initial address
new_address = translated address, or NULL if the mapping is removed
This function adds or removes an address to/from address map.

2.14. BOOL __stdcall tor_resolve_address(HANDLE plugin_instance,char *ad

dress,BOOL reverse);
 plugin_instance = the handler for current plugin instance that was retur
ned by AdvTor_InitPlugin()
address = the address that needs to be resolved
reverse = if reverse is true, a reverse lookup will be done.
Return values:
0 = the request could not be launched
1 = the request was launched
This function launches a remote hostname lookup for specified address an
d returns immediately. To get a result, the plugin must export AdvTor_TranslateA
ddress().

2.15. DWORD __stdcall choose_exit(DWORD flags,DWORD after,DWORD ip_range

_low,DWORD ip_range_high,unsigned long bandwidth_rate_min,const char *country_id
,DWORD connection_id,char *buffer);
flags = a set of bit flags, can be a combination of the following flags:
EXIT_SELECT_USE_IP_RANGE = ip_range_low and ip_range_high are us
ed
EXIT_SELECT_USE_BANDWIDTH = bandwidth_rate_min is used
EXIT_SELECT_USE_COUNTRY = country_id is valid
EXIT_SELECT_SET_CONNECTION = connection_id is valid and the conn
ection associated with it will use chosen exit
EXIT_SELECT_GET_NICKNAME = buffer is valid and it will be filled
with a string which uniquely identifies the first router that meets all require
ments
after = IP address of the previous router returned by this function or 0
.0.0.0 if this is the first call
ip_range_low = if requested exit router must be within an IP range, ip_r
ange_low is the minimum value for an IP in this range
ip_range_high = if requested exit router must be within an IP range, ip_
range_high is the maximum value for an IP in this range
bandwidth_rate_min = minimum accepted bandwidth rate, in bytes/second
country_id = a 2-letter string which identifies a country where requeste
d router can be found
connection_id = identifier of an existing connection that will use the c
hosen exit, or 0 if EXIT_SELECT_SET_CONNECTION is not set
buffer = a buffer that receives a nickname, or NULL if EXIT_SELECT_GET_N
ICKNAME is not set
Return values:
IP address of the first found router
This function searches router list for a router that is not banned, and
returns the first router that meets all requirements. Optionally, it can update
chosen exit for a connection and it can return a unique string that identifies t
he router.

2.16. BOOL __stdcall get_router_info(int index,DWORD router_ip,char *nic

kname,router_info_t *router_info);
index = 0-based enumeration index
router_ip = IP number of a router, or 0 if this value is not used
nickname = a nickname or identity hash, or NULL if nickname is not used
 router_info = a pointer to a router_info_t structure which receives info
rmation about requested router
Return values:
0 = no router was found that meets all requirements
1 = router_info was updated
This function can be used to enumerate all routers and/or to get informa
tion about a specific router.

2.17. int __stdcall is_router_banned(DWORD router_ip,char *nickname);

router_ip = IP address of a router, or 0 if only the nickname is searche
d
nickname = a unique string which identifies a router; can be a nickname
or a digest
Return values:
-1 = no router was found
0 = the router is not banned
1 = the router is banned
This function can be used to verify if a router is banned.

2.18. int __stdcall ban_router(DWORD router_ip,int ban_type,BOOL is_bann

ed);
router_ip = IP address of a router that will be banned or unbanned
ban_type = the type of ban that will be set; can be BAN_GENERAL or BAN_E
XIT
is_banned = 0 if the router will be unbanned, 1 if the router will be ba
nned
Return values:
- the number of routers that were banned or unbanned

2.19. const char * __stdcall geoip_get_country_id(DWORD ip);

ip = an IP address
Return values:
- a pointer to a 2-letter country identifier
This function searches GeoIP database for an IP address and returns a po
inter to a string that has its country identifier.

2.20. const char * __stdcall geoip_get_country_name(DWORD ip);

ip = an IP address
Return values:
- a pointer to a country name
 This function searches GeoIP database for an IP address and returns a po
inter to a string that has its country name.

2.21. long __stdcall get_time_delta(void);

This function returns number of seconds that is added to current local t
ime when the option to use fake local time is enabled.

2.22. int __stdcall crypto_rand_int(unsigned int max);

max = maximum value for a generated random number
This function returns a pseudorandom integer chosen between 0 and max.

2.23. void __stdcall randomize_buffer(char *buffer,int buffer_size);

buffer = a buffer that will have random data
buffer_size = the number of bytes that will be written to buffer
This function will write buffer_size bytes of strong random data to buff
er.

2.24. int __stdcall get_configuration_value(HANDLE plugin_instance,char

*option,char *buffer,int buffer_size);
plugin_instance = the handler for current plugin instance that was retur
ned by AdvTor_InitPlugin() or NULL if this function should return a value used b
y AdvTor.
option = variable name
buffer = a buffer that has configuration strings, each value on a new li
ne
buffer_size = maximum number of bytes that can be written
Return values:
- the number of bytes that were written to buffer, including the
null terminator
This function can return a plugin-specific configuration value (each plu
gin DLL can have its own private configuration values that are written to AdvTor
.ini) or a configuration value that is used by AdvTor.

2.25. BOOL __stdcall set_configuration_value(HANDLE plugin_instance,char

*option,char *value);
plugin_instance = the handler for current plugin instance that was retur
ned by AdvTor_InitPlugin()
option = variable name
value = a null-terminated string with values for this option, each value
on a new line; if value is NULL, the configuration option is deleted
 Return values:
0 = there was an error changing this configuration option
1 = the option was updated
This function updates a plugin-specific configuration value that can be
written to AdvTor.ini. Plugin options are private for each plugin DLL and they a
re not used by AdvTor.

2.26. BOOL __stdcall intercept_process(HANDLE plugin_instance,DWORD pid,

DWORD flags,char *local_address);
plugin_instance = the handler for current plugin instance that was retur
ned by AdvTor_InitPlugin()
pid = identifier of a process
flags = a set of bit flags, can be a combination of the following flags:
INTERCEPT_FLAG_FAKE_LOCAL_TIME - this process w
ill use fake local time
INTERCEPT_FLAG_FAKE_IPS - this process w
ill resolve all addresses to fake IPs
INTERCEPT_FLAG_TCP_ONLY - disallow non-T
CP sockets
INTERCEPT_FLAG_CHANGE_ICON - change icon to
indicate AdvTod.dll's presence
INTERCEPT_FLAG_EXCLUSIVE_EXIT - exit nodes use
d by this process cannot be simultaneously used by other processes
INTERCEPT_FLAG_NOTIFY_USER - popup a messag
e box to notify the user if the process could not be intercepted
INTERCEPT_FLAG_IGNORE_EXISTING_CONNECTIONS - don't check fo
r existing connections
local_address = a pointer to a null-terminated string specifying an addr
ess that will be returned when the process tries to get local hostname
Return values:
0 = there was an error intercepting this process
1 = the process was intercepted successfully
This function can be used to itercept another process to force its new c
onnections to go through OR network.

2.27. BOOL __stdcall create_intercepted_process(HANDLE plugin_instance,c

har *exename,DWORD flags,char *local_address);
plugin_instance = the handler for current plugin instance that was retur
ned by AdvTor_InitPlugin()
exename = a null-terminated string that specifies an executable file
flags = a set of bit flags, can be a combination of the following flags:
INTERCEPT_FLAG_FAKE_LOCAL_TIME - this process w
ill use fake local time
INTERCEPT_FLAG_FAKE_IPS - this process w
ill resolve all addresses to fake IPs
INTERCEPT_FLAG_TCP_ONLY - disallow non-T
CP sockets
INTERCEPT_FLAG_CHANGE_ICON - change icon to
indicate AdvTod.dll's presence
INTERCEPT_FLAG_EXCLUSIVE_EXIT - exit nodes use
d by this process cannot be simultaneously used by other processes
INTERCEPT_FLAG_NOTIFY_USER - popup a messag
e box to notify the user if the process could not be intercepted
local_address = a pointer to a null-terminated string specifying an addr
ess that will be returned when the process tries to get local hostname
Return values:
0 = there was an error
1 = the process was created and intercepted by AdvTor.dll
This function can be used to create a new process that will have all its
connections forced to go through OR network.

2.28. BOOL __stdcall release_process(HANDLE plugin_instance,DWORD pid);

plugin_instance = the handler for current plugin instance that was retur
ned by AdvTor_InitPlugin()
pid = identifier of a process
Return values:
0 = there was an error; the process was not found or the process
was not intercepted or AdvTor.dll could not be unloaded from it
1 = AdvTor.dll was unloaded from requested process
This function can be used to unload AdvTor.dll from an intercepted proce
ss.

2.29. BOOL __stdcall is_process_intercepted(HANDLE plugin_instance,DWORD

pid);
plugin_instance = the handler for current plugin instance that was retur
ned by AdvTor_InitPlugin()
pid = identifier of a process
Return values:
0 = the process is not intercepted
1 = the process is intercepted
This function can be used to test if a process is intercepted by AdvTor.
dll.

2.30. DWORD __stdcall create_connection(HANDLE plugin_instance,char *rem

ote_address,int remote_port,BOOL exclusive,LPARAM lParam);
plugin_instance = the handler for current plugin instance that was retur
ned by AdvTor_InitPlugin()
remote_address = the address where the exit node will connect
remote_port = the port that will be used by the exit node to connect to
remote_address
exclusive = use an exclusivity key private for this DLL to exclude exit
nodes used by other plugins or processes
lParam = initial plugin-specific parameter for this connection
Return values:
 0 = there was an error when creating this connection
any other value = an identifier for a connection
This function can be used to create a connection that goes through OR ne
twork. To send data to remote_address, the plugin should listen for AdvTor_Handl
eRead() events and write the requests to be sent to buffer_in. To read the respo
nses received from remote_address the plugin should listen for AdvTor_HandleWrit
e() events. A connection created by a plugin will have its buffer_out cleared af
ter each AdvTor_HandleWrite() event. To start sending data, the plugin should us
e connection_read().

2.31. LPARAM* __stdcall get_connection_param(HANDLE plugin_instance,DWOR

D connection_id);
plugin_instance = the handler for current plugin instance that was retur
ned by AdvTor_InitPlugin()
connection_id = unique identifier for a connection or for a hidden servi
ce client
Return values:
- NULL = this plugin cannot have LPARAM values for connections b
ecause all available parameters are already used by other plugins
- a pointer to a 32-bit value associated to this connection that
can be changed by this plugin

2.32. DWORD __stdcall accept_client(HANDLE plugin_instance,SOCKET socket

,char *remote_address,int remote_port,int exclusivity,LPARAM lParam);
plugin_instance = the handler for current plugin instance that was retur
ned by AdvTor_InitPlugin()
socket = a descriptor for a client connection that was accepted by this
plugin
remote_address = the address where the client wants to connect, or NULL
if the client is expected to send a proxy request
remote_port = the port number that will be used with remote_address
exclusivity = can have one of the following values:
EXCLUSIVITY_UNDEFINED = this connection is not associated with a
ny process/plugin chain
EXCLUSIVITY_GENERAL = this connection can only use exit nodes th
at are not used by process/plugin chains that have exclusivity enabled
EXCLUSIVITY_PROCESS = apply the exit restrictions set for the pr
ocess that created this connection
EXCLUSIVITY_PLUGIN = apply this plugin's exit restrictions
lParam = initial plugin-specific parameter for this connection
Return values:
- 0 = there was an error accepting this connection
- any other value = a connection identifier for this socket
This function can be used by plugins that can intercept other processes
to force their connections to go through the OR network.

2.33. BOOL __stdcall hs_send_reply(HANDLE plugin_instance,DWORD client_i

d,char *buffer,int buffer_size);
 plugin_instance = the handler for current plugin instance that was retur
ned by AdvTor_InitPlugin()
client_id = a unique identifier for a client connection
buffer = a pointer to a buffer that has data that will be sent
buffer_size = the number of bytes to send
Return values:
- 0 = client_id was not found or is about to be disconnected
- 1 = client_id was found and the connection is still open
This function can be used by a plugin to send a reply to a client reques
t for a hosted hidden service.

2.34. int __stdcall as_from_ip(DWORD ip);

ip = an IP address
Return values:
- an integer specifying an AS number for a requested IP or AS_UN
KNOWN if no AS was found for it
This function searches AS path database for an IP address and returns it
s AS number.

2.35. int __stdcall get_as_paths(DWORD *iplist,DWORD *buffer,int buffer_

size);
iplist = an array of IPs terminated with 0
buffer = a pointer to a buffer that receives a list of possible AS paths
separated by -1; the list is terminated by 0
buffer_size = the number of bytes that can be written
Return values:
- an integer specifying an AS number for the first IP from iplis
t
This function searches AS path database for AS paths for all IPs from ip
list and combines them to form possible shortest paths between the first IP and
the last IP passing through all IPs from iplist. AS's for IP's from iplist are O
R'ed with 0x80000000.

2.36. BOOL __stdcall is_as_path_safe(DWORD *aslist);

aslist = a buffer that contains AS paths separated by -1 that were retur
ned by a call to get_as_paths()
Return values:
- if no intersections were found in any AS path from aslist, thi
s function returns 1; if intersections are found, intersection points are OR'ed
with 0x40000000 in aslist and the function returns 0.
This function searches AS path database for an IP address and returns it
s AS number.
 2.37. void * __stdcall tor_malloc(size_t size);
size = the number of bytes that will be allocated
Return values:
- a pointer to an allocated buffer
This function never returns NULL. On error, AdvOR shows an error message
and exit. Different versions of AdvOR may have different implementations for th
is function. Version 0.2.0.12 uses malloc().

2.38. void __stdcall tor_free(void *mem);

mem = a pointer to a buffer that was allocated using tor_malloc()
This function frees a buffer that was allocated using tor_malloc().

2.39. void * __stdcall safe_malloc(size_t size);

size = the number of bytes that will be allocated
Return values:
- a pointer to an allocated buffer
- NULL if this function fails
This function attempts to allocate a buffer that will not be cached to t
he Windows swap file.

2.40. void __stdcall safe_free(void *mem);

mem = a pointer to a buffer that was allocated using safe_malloc()
This function frees a buffer that was allocated using safe_malloc().

2.41. int __stdcall write_protected_file(char *filename,char *buffer,int

bufsize);
filename = a NULL-terminated UTF-8 string that specifies a file name; th
is name can be used to read from the same file
buffer = points to the buffer containing the data to be written
bufsize = specifies the number of bytes to write
Return values:
-1 = the file could not be written
0 = the file was written successfully
If the read-only mode is enabled, the file will not be written to disk,
but it will be cached and can be read using read_protected_file(). If the option
to compress and encrypt configuration files is enabled, the file will be compre
ssed and encrypted and added to AdvOR.dat. By default, a file is written to disk
that will have a name prefixed by AdvOR's executable file name.

2.42. int __stdcall append_to_protected_file(char *filename,char *buffer

,int bufsize);
filename = a NULL-terminated UTF-8 string that specifies a file name; th
is name can be used to read from the same file
buffer = points to the buffer containing the data to be written
bufsize = specifies the number of bytes to write
Return values:
-1 = the file could not be written
0 = the file was written successfully
This function appends a buffer to a protected file. If the protected fil
e does not exist, it is created. If the read-only mode is enabled, the file will
not be written to disk, but it will be cached and can be read using read_protec
ted_file(). If the option to compress and encrypt configuration files is enabled
, the file will be compressed and encrypted and added to AdvOR.dat. By default,
a file is written to disk that will have a name prefixed by AdvOR's executable f
ile name.

2.43. int __stdcall read_protected_file(char *filename,char **buffer);

filename = a NULL-terminated UTF-8 string that specifies a file that was
written using write_protected_file() or append_to_protected_file()
buffer = points to the location where a pointer to the buffer that recei
ves the data read from the file will be written; this buffer should be freed usi
ng tor_free();
Return values:
-1 = there was an error or the file does not exist
any other value = the number of bytes that were written to buffe
r
This function reads a file that was saved using write_protected_file() o
r append_to_protected_file().

2.44. BOOL __stdcall protected_file_exists(char *filename);

filename = a NULL-terminated UTF-8 string that specifies a file that was
written using write_protected_file() or append_to_protected_file()
Return values:
0 = the file was not found
1 = the file was found (on disk or in cache)
This function can be used to verify if a protected file exists.

2.45. int tor_gzip_compress(char **buffer_out,size_t *out_len,char *buff

er_in,size_t in_len,int method);
 buffer_out = a pointer to the location where a pointer to a newly alloca
ted buffer will be written; use tor_free() to free this buffer
out_len = a pointer to the location where the size of the buffer_out buf
fer will be written
buffer_in = a pointer to a buffer that contains uncompressed data
in_len = size of uncompressed data
method = compression method; can be GZIP_METHOD or ZLIB_METHOD
Return values:
0 = success
-1 = failure
This function compresses in_len bytes from buffer_in to a newly allocate
d buffer using the reuqested method. The compressed result is stored in buffer_o
ut and the size of compressed data is written to out_len.

2.46. int tor_gzip_uncompress(char **buffer_out,size_t *out_len,const ch

ar *buffer_in,size_t in_len,int method,int complete_only,int log_level);
buffer_out = a pointer to the location where a pointer to a newly alloca
ted buffer will be written; use tor_free() to free this buffer
out_len = a pointer to the location where the size of the buffer_out buf
fer will be written
buffer_in = a pointer to a buffer that contains compressed data
in_len = size of compressed data
method = compression method; can be GZIP_METHOD or ZLIB_METHOD; use dete
ct_compression_method() if the method is uknown
complete_only = if this value is true, a truncated input is considered a
failure
log_level = the log level that will be used for all warnings shown by th
is function
Return values:
0 = success
-1 = failure
This function uncompresses in_len bytes from buffer_in to a newly alloca
ted buffer using the requested method. The uncompressed result is stored in buff
er_out and the size of decompressed data is written to out_len.

2.47. tor_zlib_state_t *tor_zlib_new(int compress,int method);

compress = 1 if this object is used for compressing data, 0 if this obje
ct is used for uncompressing data
method = compression method; can be GZIP_METHOD or ZLIB_METHOD; when dec
ompressing, use detect_compression_method() if the method is uknown
Return values:
- a tor_zlib_state_t object
This function creates a tor_zlib_state_t object that can be used with th
e tor_zlib_process() function.
 2.48. tor_zlib_output_t tor_zlib_process(tor_zlib_state_t *state,char **
buffer_out,size_t *out_len,char **buffer_in,size_t *in_len,int finish);
state = a tor_zlib_state_t object that was created with tor_zlib_new()
buffer_out = a pointer to the location where a pointer to a buffer will
be written; use tor_zlib_free() to free this buffer
out_len = a pointer to the location where the size of the buffer_out buf
fer will be written
buffer_in = a pointer to a location where a pointer to the input buffer
can be found; this function adjusts the pointer to the input buffer with the num
ber of bytes that were compressed / decompressed.
in_len = a pointer to size of compressed data; this function will adjust
the value pointed by in_len to contain the number of available bytes remaining
in buffer_in
finish = if this value is true, this is end of the input
Return values:
TOR_ZLIB_DONE = the compression/decompression was finished
TOR_ZLIB_OK = everything from the input buffer was processed
TOR_ZLIB_BUF_FULL = not enough space in buffer_out
TOR_ZLIB_ERR = the stream is corrupt
This function will compress / decompress some bytes from buffer_in using
a tor_zlib_state_t object state created by tor_zlib_new(). It reads up to in_le
n bytes from buffer_in and writes up to out_len bytes to buffer_out, adjusting a
ll values. If finish is true, the end of the input was reached.

2.49. void tor_zlib_free(tor_zlib_state_t *state);

state = a state object that was created with tor_zlib_new()
This function frees a tor_state_t object.

2.50. int detect_compression_method(char *buffer_in, size_t in_len);

buffer_in = a pointer to a buffer that has data compressed with an unkno
wn method
in_len = the size of buffer_in
Return values:
- GZIP_METHOD, ZLIB_METHOD or UNKNOWN_METHOD
This function attempts to detect the compression method that was used or
buffer_in and returns the likeliest compression method. If the buffer is not co
mpressed, or if the compression method could not be detected, this function retu
rns UNKNOWN_METHOD.

2.51. char * __stdcall lang_get_string(HANDLE plugin_instance,int string

_id,char *default_string);
plugin_instance = the handler for current plugin instance that was retur
ned by AdvTor_InitPlugin()
string_id = numerical identifier of a string from plugin's language file
default_string = a pointer to string that is returned if no language str
ing was found for current language having requested identifier; can be NULL
Return values:
- a pointer to a NULL-terminated UTF-8 encoded string from a lan
guage file.
Language files for plugins are named %[dll_name]-%[language].lng and are
located in AdvOR-plugins directory (the English language file for a plugin name
d "plugin.dll" is "plugin-English.lng"). When a new language is selected, and th
e plugin requests a new language string, the language file for current language
is loaded and parsed by AdvOR. If a string having the requested language identif
ier was found, it is returned. If no language file was found for current languag
e or no language string having the requested identifier was found, default_strin
g is returned.

2.52. void __stdcall lang_change_dialog_strings(HANDLE hPlugin,HWND hDlg

,lang_dlg_info *dlgInfo);
plugin_instance = the handler for current plugin instance that was retur
ned by AdvTor_InitPlugin()
hDlg = the parent dialog for all controls from dlgInfo
dlgInfo = a list of lang_dlg_info structures, the last structure has bot
h ctrlId and langId set to 0
This function changes the text of all dialog controls specified in the d
lgInfo list with language strings that can be found in the language file that wa
s loaded for this plugin.

3. Hidden services

If a plugin exports HiddenService_HandleRead(), it is added to hidden se

rvice selection dialog when the plugin is loaded. The function HiddenService_Han
dleRead() is the only function that is required to be exported for a plugin to b
e allowed to serve a hidden service. All other functions related to hidden servi
ces should be exported only if the plugin needs to handle events associated with
them.
The user can select the DLL for a new hidden service and associate a vir
tual port with it, and AdvTor will create an .onion address and a private key fo
r the hidden service or use an existing .onion address and an existing private k
ey. More hidden services can be served by same plugin. If the function HiddenSer
vice_NotifyService() is exported, it will be called for each hidden service that
is registered to be served by this plugin after AdvTor_InitPlugin() is called o
r when the user adds a new hidden service. When a service associated with this p
lugin is deleted, HiddenService_NotifyService() is called again to notify the pl
ugin. The function HiddenService_NotifyService() is not required for a hidden se
rvice to be registered.
All hidden service notifications are called only for the services regist
ered for this plugin on the "Hidden services" page.
When a new client connected to an .onion address that is handled by this
plugin, HiddenService_NotifyService() is called to notify the plugin if it expo
rts this function. All requests sent by a client will cause HiddenService_Handle
Read() to be called to allow the plugin to handle those requests. A plugin can r
eply to a request using hs_send_reply(). When a client is disconnected from a hi
dden service, the plugin is notified by HiddenService_NotifyService().