******************************************************************************************* Technical reference for plugin dll programming. Allowing the user to transfer control to an external dll allows complete near customization of the bot for specialized purposes. Users are encouraged to develop their own plugin dlls for ZeroBot. Following is a reference of the various features provided through the ZeroBot API. All functions which are to be called by ZeroBot must follow a specific format: unsigned long __stdcall DllProcessProc(DWORD id, const char *user, const char *text, DWORD flags, char **inserts, int insertscount, const FunctionList *botfunctions, DWORD threadid, DWORD botversion); Such functions must also be exported using a module definition (.DEF) file, rather then by __declspec(dllexport), or similar methods used only for static linkage. Explanation of parameters for a processing function: id = The Battle.net event id of the current event, minus 1000. user = The user field for the event. text = The text field for the event. flags = The flags field for the event. inserts = Array of strings which are used as config variables. %1 = inserts[0], and so on. insertscount = The number of elements in the inserts array (INCLUDING UNUSED ELEMENTS). botfunctions = Pointer to a structure containing pointers to the ZeroBot API functions. threadid = The ID of the thread which is calling the processing function. botversion = The major and minor versions of the bot. Data types used by the ZeroBot API: struct FunctionList { QueueProc *queueproc; AccesslistProc *accessproc; AllocateProc *allocateproc FreeProc *freeproc; SetupProc *setupproc; FunctionInfoProc *infoproc; void *reserved1; void *reserved2; DWORD reserved3; DWORD reserved4; } ZeroBot API functions: unsigned long __stdcall QueueProc(DWORD opcode, const char *text); Parameters: opcode = Operation to perform. text = Parameter which may or may not be used depending on the opcode. Return values: QueueProc will return 0 if the operation was completed successfully. Otherwise, an error code will be returned. Remarks: Possible opcode values are: QUEUE_ADD - add string 'text' to the queue. DO NOT APPEND A \r\n TO THE END OF THE STRING! QUEUE_CLEAR - flushes all messages out of the queue, and resets the flood protection. unsigned long __stdcall AccessListProc(DWORD opcode, const char *user, const char *flags, DWORD flag); Parameters: opcode = Operation to perform. user = Usermask to be acted on. flags = String of flags which may or may not be used depending on the opcode. flag = A single flag (character) which may or may not be used depending on the opcode. Return values: AccessListProc will return 0 if the operation was completed successfully. Otherwise, an error code will be returned. Remarks: Possible opcode values are: ACCESSLIST_ADD - add a usermask to the access list, using the flags parameter for the starting access flags for the new entry. ACCESSLIST_REMOVE - removes a usermask from the access list. ACCESSLIST_CHECK - checks to see if a usermask has a specific flag, specified with the flag parameter. ACCESSLIST_FIND - checks to see if a usermask is an entry. ACCESSLIST_SET - clears all existing flags of a usermask, and sets it's flags to the flags specified with the flags parameter. The ADD operation will fail with ACCESSLIST_ERROR_ALREADY_EXISTS if the usermask is already an entry. The REMOVE operation will fail with ACCESSLIST_ERROR_NOT_EXISTS if the usermask is not an entry. The CHECK operation will fail with ACCESSLIST_ERROR_NOT_EXISTS if the usermask is not an entry. If the usermask exists, but does not have the requested flags, then a value of ACCESSLIST_ERROR_NOT_HAVE_FLAG will be returned. The SET operation will fail with ACCESSLIST_ERROR_NOT_EXISTS if the usermask is not an entry. void *__stdcall AllocateProc(DWORD size); Parameters: size = Number of bytes to allocate. Return values: If the allocation was successful, a pointer to the allocated memory is returned. If the function failed, a NULL pointer is returned. Remarks: This function allows the dll to allocate memory (typically for usage in the inserts array). A dll should not attempt to free this memory normally. Use the FreeProc function to free memory allocated by AllocateProc. Memory allocated in this manner does not need to be freed by the processing function before it returns control to ZeroBot. Any memory not freed by the dll will automatically be freed at the end of the processing cycle of the current Battle.net event. Thus, you may allocate memory to be used in the inserts array, which can be accessed through config responses. void __stdcall FreeProc(void *address); Parameters: address = Pointer to memory allocated with AllocateProc, to be freed. Return values: This function does not return a value to the caller. Remarks: Only pass a pointer to memory allocated with AllocateProc to this function. If you pass a pointer to anything else, the result of the function is undefined, and may result in a crash. unsigned long __stdcall InfoProc(DWORD opcode, DWORD argc, void *argv); Parameters: opcode = Operation to perform. argc = Optional parameter to be used, depending on the opcode. argv = Optional parameter to be used or set, depending on the opcode. Return values: If the function succeeded, an appropriate status code will be returned. Otherwise, a value of INFO_ERROR_NOT_SUPPORTED, or another appropriate error code, will be returned. Remarks: The InfoProc function is used to query information about extensions to the ZeroBot API. To determine if a particular ZeroBot build has a certain extended feature available, call the InfoProc function, using the appropriate opcode and parameters. Updates to the API reference with regard to extended features which can be accessed through the InfoProc function will be published when a new version of the bot which supports them is released. unsigned long __stdcall SetupProc(DWORD opcode, DWORD *flags, char *params); Parameters: opcode = Operation to perform. flags = Pointer to extra options [operation-dependant]. params = Pointer to a buffer containing a string used by some operations. Return values: If the function succeeded, an appropriate status code will be returned. Otherwise, a value of SETUP_UNKNOWN_OPTION, or other appropriate error code will be returned. Remarks: The SetupProc function is used to set/retrieve many of the bot configuration settings. ZeroBot API constants: The ZeroBot API functions return a bitfield. You should use the BINARY-AND operator to test for a specific flag. The following constants are defined: #define QUEUE_NONE 0x00 #define QUEUE_ADD 0x01 #define QUEUE_CLEAR 0x02 #define ACCESSLIST_NONE 0x00 #define ACCESSLIST_ADD 0x01 #define ACCESSLIST_REMOVE 0x02 #define ACCESSLIST_CHECK 0x04 #define ACCESSLIST_FIND 0x08 #define ACCESSLIST_SET 0x10 #define ACCESSLIST_ERROR_ALREADY_EXISTS 0x01 #define ACCESSLIST_ERROR_NOT_EXISTS 0x02 #define ACCESSLIST_ERROR_NOT_HAVE_FLAG 0x04 #define INFO_NONE 0x00 #define INFO_ERROR_NOT_SUPPORTED 0x01 #define SETUP_SET 0x01 #define SETUP_GET 0x02 #define SETUP_CONFIGNAME 0x04 #define SETUP_USERNAME 0x08 #define SETUP_PASSWORD 0x10 #define SETUP_BNEMUPASSWORD 0x20 #define SETUP_BNEMUENTRY 0x40 #define SETUP_IDLE 0x80 #define SETUP_SERVER 0x100 #define SETUP_SOCKS 0x200 #define SETUP_SOCKSMETHOD 0x400 #define SETUP_UNBANSAFELISTED 0x800 #define SETUP_BOTNETSERVER 0x1000 #define SETUP_BOTNETPASSWORD 0x2000 #define SETUP_PROTECTEDCYCLE 0x4000 #define SETUP_HOMECHANNEL 0x8000 #define SETUP_PROTECT 0x10000 #define SETUP_LIBRARY 0x20000 #define SETUP_PDH 0x40000 #define SETUP_FLAGS_CURRENT_POSITION 0xffffffff #define SETUP_FLAGS_SOCKS_METHOD_4 0x01 #define SETUP_FLAGS_SOCKS_METHOD_5 0x02 #define SETUP_FLAGS_ALLOW_UNBAN_SAFE 0x01 #define SETUP_FLAGS_PREVENT_UNBAN_SAFE 0x02 #define SETUP_FLAGS_BOTNET_DISABLE 0x01 #define SETUP_FLAGS_ALLOW_UNSAFECYCLE 0x01 #define SETUP_FLAGS_PREVENT_UNSAFECYCLE 0x02 #define SETUP_FLAGS_ENABLE_PROTECT 0x01 #define SETUP_FLAGS_DISABLE_PROTECT 0x02 #define SETUP_NONE 0x00 #define SETUP_ERROR_UNKNOWN_OPTION 0x01 #define SETUP_ERROR_OUT_OF_BOUNDS 0x02 #define SETUP_ERROR_INVALID_DATA 0x04 #define SETUP_ERROR_OPTION_READ_ONLY 0x08 #define SETUP_ERROR_NOT_SUPPORTED 0x10 #define SETUP_ERROR_OPTION_NOT_UPDATED 0x20 #define SETUP_ERROR_OPTION_WRITE_ONLY 0x40 Old constant definitions: QUEUE_NONE = 0x00 QUEUE_ADD = 0x01 QUEUE_CLEAR = 0x02 ACCESSLIST_NONE = 0x00 ACCESSLIST_ADD = 0x01 ACCESSLIST_REMOVE = 0x02 ACCESSLIST_CHECK = 0x04 ACCESSLIST_FIND = 0x08 ACCESSLIST_SET = 0x10 ACCESSLIST_ERROR_ALREADY_EXISTS = 0x01 ACCESSLIST_ERROR_NOT_EXISTS = 0x02 ACCESSLIST_ERROR_NOT_HAVE_FLAG = 0x04 INFO_NONE = 0x00 INFO_ERROR_NOT_SUPPORTED = 0x01 When programming a dll processing function, you can rely on the following conditions holding true under all circumstances: 1) Only one thread at a time will be calling a processing function. 2) Event IDs between 1 and 10000 are only used when the bot is connected to Battle.net. 3) Event IDs outside of the 1-10000 range may be used when the bot is not connected to Battle.net. If your function is called with an event ID outside the 1-10000 range, you can safely assume that it is not an event from the Battle.net server, but instead an internal event generated by the bot. No action should be taken on such internal event IDs without knowing the specific conditions they are generated under, and what the event field parameters will contain. 4) If a ZeroBot API function does not return an error code, it completed it's operation successfully. The exception to this is adding a message to a queue, where it is impossible to tell if the message was queued or not (the queue is limited to 50 messages). 5) All unused inserts will be set to NULL pointers. 6) The primary interface to ZeroBot is backward-compatible. Any changes to the interface can be accessed through the infoproc API function. Furthermore, the FunctionList struct will always be the same in all ZeroBot versions. 7) The constants defined in the ZeroBot API will always have the same values, although new constants may be added at a later time.