1. Functions that are called by AdvTor if the plugin exports them 1.1. int __stdcall AdvTor_InitPlugin(HANDLE plugin_instance,DWORD version,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 specifying plugin description (UTF-8) function_table = a pointer to an array of functions that can be called by this plugin, for more information see plugins.h Return values: 0 = initialization failed and the plugin cannot be loaded at this time 1 = initialization was successfull This is the first function that is called by AdvTor after loading a plugin 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 anyway (in this case, AdvTor_UnloadPlugin will be called again with PLUGIN_UNLOAD_MUST_UNLOAD) or to cancel unloading (in this case, AdvTor_UnloadPlugin will be called again with PLUGIN_UNLOAD_CANCEL) 1 = the plugin can be unloaded and FreeLibrary will 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 will be called -1 = the plugin cannot be unloaded, but AdvTor_InitPlugin 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 anyway (in this case, AdvTor_UnloadPlugin will be called again with PLUGIN_UNLOAD_MUST_UNLOAD) or to cancel unloading (in this case, AdvTor_UnloadPlugin will be called again with PLUGIN_UNLOAD_CANCEL) 1 = the plugin can be unloaded and FreeLibrary will be called PLUGIN_UNLOAD_MUST_UNLOAD = the user selected the option to unload the plugin anyway and FreeLibrary will be called no return values PLUGIN_UNLOAD_CANCEL = unloading this plugin was canceled by user no return values This function is called before unloading the library or when the user cancels 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 AdvTor page If this function is exported, AdvTor will add a new option for this plugin's window and will call it to get a window handle that can be shown as a separate page with configuration options related to this plugin. This function is only called when the user clicks on the option related to this plugin to see the options for the first time after the plugin was (re)initialized. The size and visibility of this window are controlled by AdvTor. The plugin must not create the configuration 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_CLIPCHILDREN | 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 configuration window Return values: - an array of resize_info_t structures that will be used to resize or move dialog items to fit the new window dimensions; the last structure must have ctrlId=0 - NULL if the plugin handles WM_SIZE events If this function is exported, it is called before the configuration window is resized. Using -1 for for the first reference.left value will determine AdvTor to initialize reference rectangles using flags and current values for positions 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 and scrolling; if AdvOR should handle scroll bars and scrolling, the messages WM_HSCROLL 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 this 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 this connection or if the socket is not connected lParam = a pointer to a 32-bit value that can be associated by this plugin to this connection, or NULL if all available parameters are already used by other plugins; this value is not changed by AdvTor Return values: 0 = close this connection; the function that needs this connection will fail whatever it is trying to do 1 = register this connection; other plugins can disallow registering this connection 1.5. int __stdcall AdvTor_UnregisterConnection(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 this connection or if the socket is not connected lParam = a pointer to a 32-bit value that can be associated by this plugin to this connection, or NULL if all available parameters are already used by other plugins; this value is not changed by AdvTor Return values: 0 = don't close this connection; AdvTor_UnregisterConnection will 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_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 plugins.h address = remote address buffer_in = a buffer that has data that was read from a socket or that was 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 plugin to this connection, or NULL if all available parameters are already used by other 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 data_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 plugins.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_out lParam = a pointer to a 32-bit value that can be associated by this plugin to this connection, or NULL if all available parameters are already used by other 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 data_size. If other plugins already cleared buffer_out, 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_out. 1.8. int __stdcall AdvTor_TranslateAddress(DWORD connection_id,const char *original_address,char *translated_address,LPARAM *lParam,BOOL is_error); connection_id = unique identifier for the connection that is about to connect to this address or 0 if the address is not associated with an existing connection original_address = the address that was sent by a client or by AdvTor.dll translated_address = final address that will be used by AdvTor with OR connections; can point to original_address lParam = a pointer to a 32-bit value that can be associated by this plugin to this connection, or NULL if all available parameters are already used by other plugins ...
TEAM-BLZ