This file serves as documentation for wonton's core functions. 1) Overview a) What are the wonton core set of functions all about? b) What are handlers? 2) Core Componenents a) Memory Management b) Module Management c) Lowlevel handlers d) Scheduler e) Networking i) IRC ii) DCC f) Configuration g) Logging h) Miscellaneous 3) Structure Glossary a) Core 1) WON_CTX b) Module 1) WON_MODULE_CTX 2) WON_IC c) Scheduler 1) WON_SCHEDULED_TASK d) Networking 1) IRC a) WON_IRC_CONNECTION b) WON_IRC_PACKET 2) DCC a) WON_DCC_CONNECTION b) WON_DCC_PACKET 3) Misc. a) WON_PACKET e) Configuration 1) WON_CONFIG_PACKET 4) Function Glossary a) Memory 1) wonMemoryAllocate 2) wonMemoryReallocate 3) wonMemoryFree b) Module 1) wonModuleLoad 2) wonModuleUnload 3) wonModuleDeferredUnload 4) wonModuleCleanup 5) wonModuleIoctl 6) wonModuleBroadcastIoctl c) Lowlevel 1) wonLowlevelRecvRegisterLayeredHandler 2) wonLowlevelRecvDeregisterLayeredHandler 3) wonLowlevelSendRegisterLayeredHandler 4) wonLowlevelSendDeregisterLayeredHandler d) Scheduler 1) wonSchedulerRegister 2) wonSchedulerDeregisterById 3) wonSchedulerDeregisterByCallback e) Networking 1) IRC a) wonIrcCreateConnection b) wonIrcDestroyConnection c) wonIrcEnum d) wonIrcSend e) wonIrcGetConnectionByHandle f) wonIrcRegisterLayeredHandler g) wonIrcDeregisterLayeredHandler 2) DCC a) wonDccRegisterConnection b) wonDccDeregisterConnection c) wonDccEnum d) wonDccSend e) wonDccSendAll f) wonDccGetConnectionByHandle g) wonDccRegisterLayeredHandler h) wonDccDeregisterLayeredHandler f) Configuration 1) wonConfigurationSave 2) wonConfigurationReload 3) wonConfigRegisterLayeredHandler 4) wonConfigDeregisterLayeredHandler g) Logging 1) wonLog h) Miscellaneous 1) wonWildcardMatch 2) wonCreateTcpConnection ------------------------------------------------------------------------------- 1) Overview a) What are the wonton core set of functions all about? The wonton core set of functions were designed to be generic enough to support multitudes of modules using them as a medium by which to communicate not only with one another but to also drive the operation of the bot itself. These functions are exported with the hope that module makers find them to be tool enough to get the job done. The exported functions themself operate on the wonton context which is used to tell the wonton loader what to do. b) What are handlers? Handlers are synonomous with callbacks. A callback is easiest to be thought about as the action in an Event-Action architecture. For every event there is one or more appropriate actions. With that said, an example of such an architecture could be a pitcher throwing a baseball. This event could have one or more actions executed because of it, for instance, the batter could swing and hit the ball. This series of things could be represented in code as: if (event == PITCHER_BASEBALL_PITCH) batterSwingBat(); The way wonton uses callbacks is done more abbstractly than this. Keeping in mind the previous example, wonton basically allows for a user to supply the batterSwingBat function to be called instead of having it hard-coded. If this were applied to the previous example, the C code would be something like this: void (*batterSwingBat)() = mySwingBatFunction; if (event == PITCHER_BASEBALL_PITCH) batterSwingBat(); This code effectively calls mySwingBatFunction. Since wonton allows for dynamic application of functions associated with any given event, the power is virtually limitless in its domain. 2) Core Components a) Memory Management Wonton provides the module maker with a small set of functions that help make it so the programmer is not required to worry about null pointers. For instance, wonMemoryAllocate will never return null. It will continue to attempt to allocate memory until a valid pointer is returned. Respectively, wonMemoryFree will not attempt to free null pointers which are passed in. This gives the programmer the added luxery of not having to do the tedious memory checks they would otherwise have to do with very little sacrifice with regards to efficiency. b) Module Management Wonton itself is all module driven. Nothing in the loader operates directly on connections to the internet. It's the job of modules to make wonton do anything at all. The most noteable module is wonkrnl which uses the core functions to provide basic DCC and IRC functionality that most any bot that exists today allows for. With that said, it should be implied that wonton is capable of both loading and unloading modules. As an added benefit, the core module functions allow for communication between modules which are loaded through a mechanism referred to as IOCTL's. To those familiar with kernel development on both windows and unix, you should be get the jist for how wonton operates IOCTL's. For those who aren't, IOCTL's can best be thought of as a way of sending a message from one module to another and then allowing for the ability for the sending module to receive a response. Please see the [wonton-modules] documentation for more details on how IOCTL's are implemented and used. c) Lowlevel Handlers In order to allow for the most direct control of data passing over connections which wonton establishes a set of lowlevel handlers have been created for modules that require direct data access. These handlers get called before any specific parse-based handlers are called (see IRC and DCC Handlers). Right after data is read off the socket, all wonton lowlevel receive handlers will be called. Right before data is sent, all wonton lowlevel send handlers will be called. In order to allow certain modules the flexibility of "claiming" an incoming packet, said handlers can return a status code of WON_STATUS_CLAIMPACKET if they do not want any parse-based handlers to be called which will also prohibit any further lowlevel handlers down the list from getting called. d) Scheduler Since the wonton loader itself has been coded in a single thread environment it was important to create a mechanism by which modules could schedule certain tasks to be completed at certain intervals. For instance, one module may want to save configuration every 5 minutes which would be hard to do accurately in a single threaded environment. The scheduler makes it possible to do this to within-the-second results. e) Networking i) IRC The IRC network subsystem are a collection of functions that make it so the module maker can establish and handle connections to one or more IRC server/network simultaneously. ii) DCC The DCC network subsystem are also a collection of functions that make it so the module maker can establish and handle connections to one or more DCC connections simultaneously. f) Configuration A centralized configuration system has been established in order to make it possible for all modules to have their own configuration section in one core configuration file. All modules have the ability to both save and reload the configuration at any point. g) Logging Logging facilities have been exported for both debugging and informational purposes. Any module has the ability to log to the underlying log file. This ability of course does not limit another module from creating its own logging subsystem. h) Miscellaneous There are two miscellaneous functions which have been exported by the core which enable modules to wildcard match and create tcp connections. 3) Structure Glossary a) Core 1) WON_CTX The WON_CTX is the core context struct. Every option requires a pointer to this context. It contains the following information: short intialized Whether or not it has been initialized. uint32 startTime The time the core was initialized. uint32 moduleCount The number of modules loaded. short wantComplete [internal use only] Reserved. uint32 pid The PID if forked. char *configurationFile The configuration file to be parsed and saved to. WON_CONNECTION wonConnections[] [internal use only] An array of wonton connections. uint32 numConnections Total number of connections established. int highestFd [internal use only] highest file descriptor. LINKED_LIST moduleList Linked list of all modules loaded. HASH_GROUP moduleHash Hash of all the modules loaded. LINKED_LIST ircConnections Linked list of all irc connections. LINKED_LIST dccConnections Linked list of all dcc connections. LINKED_LIST schedulerList Linked list of all scheduled tasks. HASH_GROUP ircHandlers Hash of all irc handlers. HASH_GROUP dccHandlers Hash of all dcc handlers. HASH_GROUP configHandlers Hash of all config handlers. LINKED_LIST lowlevelRecvHandlers Linked list of all lowlevel receive handlers. LINKED_LIST lowlevelSendHandlers Linked list of all lowlevel send handlers. FILE *logfd File descriptor for the log mechanism. char *logFile The location of the log file. b) Module 1) WON_MODULE_CTX The module context structure is used to hold information about a loaded module such as its size, path, name, and function pointers. WON_CTX *ctx A pointer to the core context. void *moduleHandle A pointer to the handle returned by dlopen() void *moduleExtension A pointer to a module defined module extension uint32 (*moduleLoad)(WON_MODULE_CTX *modctx) A pointer to the wonLoad function inside the module. This value may be NULL. uint32 (*moduleIoctl)(WON_MODULE_CTX *modctx, uint32 ioctl, void *wic) A pointer to the wonIoctl function inside the module. This value may be NULL. uint32 (*moduleUnload)(WON_MODULE_CTX *modctx) A pointer to the wonUnload function inside the module. This value may be NULL. char *moduleName The name of the module. char *modulePath The path to the modules binary. uint32 moduleSize The size of the module when loaded. 2) WON_IC This structure is used to send and receive information sent via IOCTL. WON_MODULE_CTX *modctx The context of the module requesting the IOCTL. This value may be NULL. void *inBuffer This is in the parameter which can be anything. uint32 inLen This specifies the length of the inBuffer. void *outBuffer This is a pointer to the return value. uint32 outLen This is the size of the return length. c) Scheduler 1) WON_SCHEDULED_TASK This structure contains all the information of any one specific scheduled task. WON_CTX *ctx A pointer to the core context. WON_MODULE_CTX *modctx A pointer to the module that scheduled the task. uint32 id The identifier for this scheduled task. uint32 timeFrame The time between executions in seconds. uint32 executeTimes The number of times to execute, -1 for infinite. void *schedulerContext Optional value to be passed into the callback function. uint32 (*callback)(WON_SCHEDULED_TASK *task) The actual function pointer to call. uint32 lastExecute The last time the task was executed. d) Networking 1) IRC a) WON_IRC_CONNECTION This structure stores information about an IRC connection. unsigned long addr The IP address of the remote machine. unsigned int port The port of the remote machine. int fd The file descriptor currently used. unsigned int state The current state of the irc connection. WON_IRC_STATE_CONNECTED -> TCP up WON_IRC_STATE_ONLINE -> Signed on char *nickname The nickname of the current connection. void *ircExtension A pointer to an optional connection extension. b) WON_IRC_PACKET This structure is passed to every handler registered for an irc connection. WON_CTX *ctx A pointer to the core context. WON_MODULE_CTX *modctx A pointer to the module that registered the handler. WON_IRC_CONNECTION *irc A pointer to the irc connection associated with the packet. CACHE *buffer The word parsed buffer read from the socket. char *fromNick The nickname the packet came from if applicable char *fromMask The mask of the source nickname if applicable 2) DCC a) WON_DCC_CONNECTION This structure contains information about a given DCC connection. int fd The file descriptor of the connection. unsigned long addr The remote address. unsigned int port The remote port. unsigned int state The state of the dcc connection. WON_DCC_STATE_USERNAME -> recv'd username WON_DCC_STATE_AUTH -> authenticated void *dccExtension An optional extension. b) WON_DCC_PACKET WON_CTX *ctx A pointer to the core context. WON_MODULE_CTX *modctx A pointer to the module that registered the handler. WON_DCC_CONNECTION *dcc A pointer to the dcc connection associated with the packet. CACHE *buffer The word parsed buffer read from the socket. 3) Misc. a) WON_PACKET This structure is used only with lowlevel handlers. It encapsulates a given DCC or IRC packet into one packet. short type The type of connection. WON_CONNECTION_IRC, WON_CONNECTION_DCC union { WON_IRC_PACKET *irc Used if there is an irc packet WON_DCC_PACKET *dcc Used if there is a dcc packet } pkt Link between the two. e) Configuration 1) WON_CONFIG_PACKET This structure is passed to any registered configuration handlers when their criteria is met. WON_CTX *ctx A pointer to the core context. WON_MODULE_CTX *modctx A pointer to the module that registered the handler. CACHE *buffer The word parsed buffer read from the file. uint32 lineNumber The current line number of the configuration file. 4) Function Glossary Any use of the following functions requires that one include won.h. a) Memory 1) wonMemoryAllocate void *wonMemoryAllocate(unsigned int size, short zeroMemory); Parameters: size The size of memory to allocate. zeroMemory Whether or not to zero the allocated memory. This function will always return a valid pointer that was dynamically allocated to size bytes. If the zero memory flag is set to 1 then the newly allocated memory will be memset to 0x00. 2) wonMemoryReallocate void *wonMemoryReallocate(void *ptr, unsigned int newSize); Parameters: ptr The pointer to reallocate. newSize The size you want the pointer to become. This function will always return a valid pointer that has been reallocated to newSize. The ptr passed in is the pointer that is reallocated. 3) wonMemoryFree void wonMemoryFree(void *ptr); Parameters: ptr The pointer in memory to free. This function will attempt to deallocate the specified pointer assuming that it's not null. If the incoming pointer is null the function will return immediately. b) Module 1) wonModuleLoad WON_STATUS wonModuleLoad(WON_CTX *ctx, const char *modulePath, const char *moduleName); Parameters: ctx The wonton core context. modulePath The pathname to a module. Ex: /usr/src/wonton/modules/mod.so moduleName The name to associate with the module. Ex: mod This function will attempt to load the module located at modulePath and will associate with moduleName once loaded. If a module already exists with the name moduleName then the function will return with WON_STATUS_EXISTS. If the attempt to load the module fails the function will return with WON_STATUS_FAILURE. If everything succeeds the return value will be WON_STATUS_SUCCESS. 2) wonModuleUnload WON_STATUS wonModuleUnload(WON_CTX *ctx, const char *moduleName); Parameters: ctx The wonton core context. moduleName The module name to unload. Ex: mod This function will attempt to unload the specified module. This function should NOT be called inside a function local to the specified moduleName. If this is the case, wonModuleDeferredUnload should be called. If the specified module does not actually exist the function will return WON_STATUS_NOEXISTS. If the wonUnload routine that the module implements returns WON_STATUS_FAILURE then the unload will fail. Otherwise, WON_STATUS_SUCCESS is returned and the module is removed from memory. All references to handlers that existed inside this module are cleaned up at this point if the module did not perform proper cleanup. 3) wonModuleDeferredUnload WON_STATUS wonModuleDeferredUnload(WON_CTX *ctx, const char *moduleName); Parameters: ctx The wonton core context. moduleName The module name to unload. Ex: mod This function will unload a module one second after the function is called. This allows for modules to unload themselves. If the scheduling of the tasks fails WON_STATUS_FAILURE will be returned. Otherwise, WON_STATUS_SUCCESS is returned. 4) wonModuleCleanup void wonModuleCleanup(WON_CTX *ctx, WON_MODULE_CTX *modctx); Parameters: ctx The wonton core context. modctx The module context to cleanup. NOTE: It is not recommended that this function be called by modules. This function is strictly used by the core system to clean up links to modules which are being unloaded, such as handlers which call functions inside the module itself. 5) wonModuleIoctl WON_STATUS wonModuleIoctl(WON_CTX *ctx, const char *moduleName, uint32 ioctl, WON_IC *wic); Parameters: ctx The wonton core context. moduleName The module name to communicate with. Ex: mod ioctl The IOCTL to send. Ex: 24 (dest module interprets) wic A wonton IOCTL structure. This function sends a message to another module via calling the destination modules wonIoctl function (if it exists). If it does exist, the parameters are passed in and operated on. The return value will either be WON_STATUS_NOEXISTS if the destination module does not exist or a variant of responses depending on what the wonIoctl function returns inside the destination module. 6) wonModuleBroadcastIoctl WON_STATUS wonModuleBroadcastIoctl(WON_CTX *ctx, uint32 ioctl, void *inBuffer, uint32 inLen); Parameters: ctx The wonton core context. ioctl The ioctl to broadcast. inBuffer The inBuffer to use as part of the WON_IC. inLen The length of the inBuffer. This function will broadcast a given IOCTL to all loaded modules. It will always return WON_STATUS_SUCCESS. c) Lowlevel 1) wonLowlevelRecvRegisterLayeredHandler WON_STATUS wonLowlevelRecvRegisterLayeredHandler( WON_CTX *ctx, WON_MODULE_CTX *modctx, short layerPreference, uint32 (*func)(WON_MODULE_CTX *,WON_PACKET *)); Parameters: ctx The wonton core context. modctx The context of the module that is registering the handler. layerPreference Whether to layer in front of back (WON_LAYER_FIRST, WON_LAYER_LAST respectively) func The function to register as the handler. This function will register a function inside a module as being a lowlevel receive handler. A lowlevel receive handler is called everytime a full length packet is received by the wonton loader. This function will return WON_STATUS_FAILURE if the given function is already registered as a lowlevel handler or will return WON_STATUS_SUCCESS if all goes well. 2) wonLowlevelRecvDeregisterLayeredHandler WON_STATUS wonLowlevelRecvDeregisterLayeredHandler( WON_CTX *ctx, uint32 (*func)(WON_MODULE_CTX *,WON_PACKET *)); Parameters: ctx The wonton core context. func The function to deregister. This function will deregister a previously registered receive handler which will remove it from the list of callbacks. This function will always return WON_STATUS_SUCCESS. 3) wonLowlevelSendRegisterLayeredHandler WON_STATUS wonLowlevelSendRegisterLayeredHandler( WON_CTX *ctx, WON_MODULE_CTX *modctx, short layerPreference, uint32 (*func)(WON_MODULE_CTX *,WON_PACKET *)); Parameters: ctx The wonton core context. modctx The context of the module that is registering the handler. layerPreference Whether to layer in front of back (WON_LAYER_FIRST, WON_LAYER_LAST respectively) func The function to register as the handler. This function will register a function inside a module as being a lowlevel send handler. A lowlevel send handler is called everytime a full length packet is sent by the wonton loader. This function will return WON_STATUS_FAILURE if the given function is already registered as a lowlevel handler or will return WON_STATUS_SUCCESS if all goes well. 4) wonLowlevelSendDeregisterLayeredHandler WON_STATUS wonLowlevelSendDeregisterLayeredHandler( WON_CTX *ctx, uint32 (*func)(WON_MODULE_CTX *,WON_PACKET *)); Parameters: ctx The wonton core context. func The function to deregister. This function will deregister a previously registered send handler which will remove it from the list of callbacks. This function will always return WON_STATUS_SUCCESS. d) Scheduler 1) wonSchedulerRegister WON_STATUS wonSchedulerRegister( WON_CTX *ctx, WON_MODULE_CTX *modctx, uint32 *schedulerId, uint32 timeFrame, uint32 executeTimes, uint32 (*func)(WON_SCHEDULED_TASK *task), void *schedulerContext); Parameters: ctx The wonton core context. modctx The context of the module requesting to schedule the task. schedulerId A pointer that will optionally store the id of the scheduled task. This parameter can be NULL. timeFrame The time between executions measured in seconds. executeTimes The number of times to execute. Specify -1 for infinite. func The function to call when it's time to execute the scheduled task. schedulerContext An optional context that will be passed in as a part of the WON_SCHEDULED_TASK struct. This function allows a given module to schedule a task that will execute every timeFrame for executeTimes amount of times. A task is simply defined as a call to a function. Due to the single threaded nature of the wonton loader the scheduler system adds greater flexibility and precision to tasks that need to happen at certain intervals. This function will return WON_STATUS_FAILURE if the incoming function is not valid. Otherwise, WON_STATUS_SUCCESS will be returned. 2) wonSchedulerDeregisterById WON_STATUS wonSchedulerDeregisterById( WON_CTX *ctx, uint32 schedulerId); Parameters: ctx The wonton core context. schedulerId The id of a previously scheduled task. This function will remove scheduled tasks by the id that they were assigned upon creation. WON_STATUS_FAILURE will be returned if the scheduled task could not be removed, otherwise WON_STATUS_SUCCESS is returned. 3) wonSchedulerDeregisterByCallback WON_STATUS wonSchedulerDeregisterByCallback( WON_CTX *ctx, uint32 (*func)(WON_SCHEDULED_TASK *)); Parameters: ctx The wonton core context. func The function pointer to unschedule. This function will remove a scheduled task by the function pointer that was supplied when it was scheduled. If no task was scheduled with the given function pointer then WON_STATUS_FAILURE will be returned, otherwise WON_STATUS_SUCCESS is returned upon successful expunging. e) Networking 1) IRC a) wonIrcCreateConnection WON_STATUS wonIrcCreateConnection( WON_CTX *ctx, unsigned long bindaddr, unsigned char *dst, uint32 port); Parameters: ctx The wonton core context. bindaddr The binding address (virtual host). dst The destination address. port The destination port. This function will attempt to create a connection to an IRC server. If the TCP connection cannot be established the return value will be WON_STATUS_FAILURE. Otherwise the return value will be WON_STATUS_SUCCESS. NOTE: Just because WON_STATUS_SUCCESS is returned from this function does not necessarily mean the connection is up. A well formed module will wait for the WON_IOCTL_IRC_LINK_UP ioctl before doing anything related to that connection. b) wonIrcDestroyConnection WON_STATUS wonIrcDestroyConnection( WON_CTX *ctx, WON_IRC_CONNECTION *irc); Parameters: ctx The wonton core context. irc The IRC connection. This function will disconnect and destroy an established IRC connection. When this function is called all modules are alerted that the connection is going to be going down via the WON_IOCTL_IRC_LINK_DOWN ioctl. c) wonIrcEnum WON_STATUS wonIrcEnum( WON_CTX *ctx, uint32 ircConnNumber, WON_IRC_CONNECTION **irc); Parameters: ctx The wonton core context. ircConnNumber A number 0 through x representing the connection number to obtain. irc The out value to store the irc connection in. This function is used to enumerate through the list of IRC connections. The function will continue to return WON_STATUS_SUCCESS until ircConnNumber is greater than the current number of connections in which case it will return WON_STATUS_FAILURE. d) wonIrcSend WON_STATUS wonIrcSend( WON_CTX *ctx, WON_IRC_CONNECTION *irc, const char *fmt, ...) Parameters: ctx The wonton core context. irc The IRC connection to send across. fmt The format of the data to be sent. ... Variable argument list. This function will send data specified in a printf style format across an IRC connection. Before sending all lowlevel send handlers will be called with the data about to be sent. If all lowlevel handlers return without returning WON_STATUS_FAILURE, the data will be sent aross the wire. If any of the lowlevel send handlers returns WON_STATUS_FAILURE then the outbound packet will be dropped. In every other scenario WON_STATUS_SUCCESS will be returned. e) wonIrcGetConnectionByHandle WON_IRC_CONNECTION *wonIrcGetConnectionByHandle( WON_CTX *ctx, int fd); Parameters: ctx The wonton core context. fd The file descriptor of the IRC connection. This function will return the pointer of an IRC connection that is correlated with the fd if one exists. Otherwise, the return value is NULL upon failure. f) wonIrcRegisterLayeredHandler WON_STATUS wonIrcRegisterLayeredHandler( WON_CTX *ctx, WON_MODULE_CTX *modctx, short layerPreference, const char *word, int position, uint32 (*func)(WON_IRC_PACKET *wip)); Parameters: ctx The wonton core context. modctx The module registering the handler. layerPreference Whether to layer first or last in the list. (WON_LAYER_FIRST, WON_LAYER_LAST) word The word to watch for. position The position to watch for the word in. func The function to call when the criteria is satisfied. This macro registers the provided function as a callback to be used when 'word' occurs at the given 'position' in a sentence. Positions start from 0. If someone wanted a function be called everytime the word 'BOB' showed up at position 5 they would do: wonIrcRegisterLayeredHandler(ctx, modctx, "BOB", 5, myFunction); g) wonIrcDeregisterLayeredHandler WON_STATUS wonIrcDeregisterLayeredHandler( WON_CTX *ctx, WON_MODULE_CTX *modctx, const char *word, int position, uint32 (*func)(WON_IRC_PACKET *wip)); Parameters: ctx The wonton core context. modctx The module registering the handler. word The word to watch for. position The position to watch for the word in. func The function to call when the criteria is satisfied. This macro deregisters a previously established handler for the word at the specified position for IRC connections. 2) DCC a) wonDccRegisterConnection WON_STATUS wonDccRegisterConnection( WON_CTX *ctx, WON_DCC_CONNECTION *dcc); Parameters: ctx The wonton core context. dcc The dcc connection to register. This function registers an already established DCC connection with the wonton core. The return value will always be WON_STATUS_SUCCESS. b) wonDccDeregisterConnection WON_STATUS wonDccDeregisterConnection( WON_CTX *ctx, WON_DCC_CONNECTION *dcc); Parameters: ctx The wonton core context. dcc The dcc connection to deregister. This function will remove a dcc connection from the list of established dcc connections and do any cleanup required. The return value will always be WON_STATUS_SUCCESS. c) wonDccEnum WON_STATUS wonDccEnum(WON_CTX *ctx, uint32 dccConnNumber, WON_DCC_CONNECTION **dcc); Parameters: ctx The wonton core context. dccConnNumber The dcc connection number (starts at 0). dcc The out value to store the connection at that index. This function enables you to enumerate the list of DCC connections currently established. It will continue to return WON_STATUS_SUCCESS until dccConnNumber is greater than the number of DCC conncections at which point it will return WON_STATUS_FAILURE. d) wonDccSend WON_STATUS wonDccSend(WON_CTX *ctx, WON_DCC_CONNECTION *dcc, const char *fmt, ...); Parameters: ctx The wonton core context. dcc The DCC connection to send to. fmt The format for the va_list. ... The variable arguments. This function will send data specified in a printf style format across a DCC connection. Before sending all lowlevel send handlers will be called with the data about to be sent. If all lowlevel handlers return without returning WON_STATUS_FAILURE, the data will be sent aross the wire. If any of the lowlevel send handlers returns WON_STATUS_FAILURE then the outbound packet will be dropped. In every other scenario WON_STATUS_SUCCESS will be returned. e) wonDccSendAll WON_STATUS wonDccSendAll(WON_CTX *ctx, const char *fmt, ...); Parameters: ctx The wonton core context. fmt The format for the va_list. ... The variable arguments. This function will broadcast a string to all established DCC connections. Before sending the data to each individual connection the underlying send handlers are called. If any one of the send handlers returns WON_STATUS_FAILURE then the sending is aborted and the function returns. Otherwise, the function returns WON_STATUS_SUCCESS. f) wonDccGetConnectionByHandle WON_DCC_CONNECTION *wonDccGetConnectionByHandle( WON_CTX *ctx, int fd); Parameters: ctx The wonton core context. fd The file descriptor of a dcc connetion. This function will return a pointer to an established DCC connection if one exists. Otherwise, the return value is NULL. g) wonDccRegisterLayeredHandler WON_STATUS wonDccRegisterLayeredHandler( WON_CTX *ctx, WON_MODULE_CTX *modctx, short layerPreference, const char *word, int position, uint32 (*func)(WON_DCC_PACKET *wdp)); Parameters: ctx The wonton core context. modctx The module registering the handler. layerPreference Whether to layer first or last in the list. (WON_LAYER_FIRST, WON_LAYER_LAST) word The word to watch for. position The position to watch for the word in. func The function to call when the criteria is satisfied. This macro registers the provided function as a callback to be used when 'word' occurs at the given 'position' in a sentence. Positions start from 0. If someone wanted a function be called everytime the word 'BOB' showed up at position 5 they would do: wonDccRegisterLayeredHandler(ctx, modctx, "BOB", 5, myFunction); h) wonDccDeregisterLayeredHandler WON_STATUS wonDccDeregisterLayeredHandler( WON_CTX *ctx, WON_MODULE_CTX *modctx, const char *word, int position, uint32 (*func)(WON_DCC_PACKET *wdp)); Parameters: ctx The wonton core context. modctx The module registering the handler. word The word to watch for. position The position to watch for the word in. func The function to call when the criteria is satisfied. This macro deregisters a previously established handler for the word at the specified position for DCC connections. f) Configuration 1) wonConfigurationSave WON_STATUS wonConfigurationSave(WON_CTX *ctx); Parameters: ctx The wonton core context. This function will save the log_file and load_module information to the specified configuration file as well as broadcasting the WON_IOCTL_CONFIG_SAVE ioctl that any modules can handle should they wish to save configuration data. 2) wonConfigurationReload WON_STATUS wonConfigurationReload(WON_CTX *ctx); Parameters: ctx The wonton core context. This function will call an internal function that reloads and reparses the configuration file. This function will always return WON_STATUS_SUCCESS. 3) wonConfigRegisterLayeredHandler WON_STATUS wonConfigRegisterLayeredHandler( WON_CTX *ctx, WON_MODULE_CTX *modctx, short layerPreference, const char *word, uint32 (*func)(WON_CONFIG_PACKET *wcp)); Parameters: ctx The wonton core context. modctx The wonton module context registering the handler. layerPreference Whether to layer it first or last in the list. (WON_LAYER_FIRST, WON_LAYER_LAST) word The word to watch for. This word must occur in position 0. func The function to call when the criteria is satisified. This function will register a configuration handler that will be used when the configuration file is read. 4) wonConfigDeregisterLayeredHandler WON_STATUS wonConfigDeregisterLayeredHandler( WON_CTX *ctx, WON_MODULE_CTX *modctx, const char *word, uint32 (*func)(WON_CONFIG_PACKET *wcp)); Parameters: ctx The wonton core context. modctx The wonton module context deregistering the handler. word The word that was previously hooked. func The function that was associated with the word. This function will deregister a previously established configuration handler. g) Logging 1) wonLog WON_STATUS wonLog(WON_CTX *ctx, WON_MODULE_CTX *modctx, const char *fmt, ...); Parameters: ctx The wonton core context. modctx The wonton module context that is logging an event. This parameter can be NULL. fmt The fmt for the va_list. ... The variable arguments. This function will log to a specified log file with a timestamp. h) Miscellaneous 1) wonWildcardMatch int wonWildcardMatch(unsigned char *wildcardStr, unsigned char *realStr); Parameters: wildcardStr The string containg wildcard characters. realStr The string to compare against those wildcard characters. This function will evaluate the comparison of two strings using wildards as acceptable forms of matching. (? *). 2) wonCreateTcpConnection int wonCreateTcpConnection(unsigned long bindaddr, const char *dst, unsigned int port, unsigned long *resolveaddr); Parameters: bindaddr The address to bind to (virtual host). dst The destination address. port The destination port. resolveaddr Pointer to store the resolved address of dst. This function will create a tcp connection. On success, the file descriptor will be returned, on failure 0 will be returned.