home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 35 Internet / 35-Internet.zip / bx75p3.zip / doc / plugins < prev    next >
Text File  |  1999-02-23  |  4KB  |  116 lines
  1.  
  2.             BitchX Plugins
  3.             Written by Colten Edwards (c) 1997
  4.  
  5.  
  6. Plugins can be created for BitchX quite easily. All plugins you create will
  7. have a startup function which is based on the filename of the plugin and 
  8. _Init appended to it. So for a module like cavlink.so we have a startup
  9. function called Cavlink_Init(). Cavlink_Init is defined as the following
  10.  
  11. int Cavlink_Init(IrcCommandDll **interp)
  12. {
  13. }
  14.  
  15. returning a 0 indicates successful installation, any other return is an
  16. error.
  17.  
  18. You can add various commands, variables, functions, tcl functions, and ctcp
  19. to the main client itself. You have complete access to ALL variables defined
  20. within BitchX itself. 
  21.  
  22. There is also a functions that may or may not be defined by you called the
  23. fini function. Once again it's based on the filename appended with _Cleanup
  24. to give us
  25.  
  26. int Cavlink_Cleanup(IrcCommandDll **interp)
  27. {
  28. }
  29.  
  30. If you make a cleanup function, you are responsible for removing all traces
  31. of your dll from the client.
  32.  
  33. Adding a new command/function/var in a plugin is made easier with a function
  34. that I wrote to add them to BitchX while keeping track of what's loaded.
  35.  
  36. add_module_proc(type, module name, command name, description, 
  37.         id, flag, function1, function2);
  38.  
  39. type can be any of the following
  40.     COMMAND_PROC    (internal /command)
  41.     ALIAS_PROC    (internal function)
  42.     CTCP_PROC    (ctcp procedure)
  43.     VAR_PROC    (a /set variable)
  44.     HOOK_PROC    (like a /on hook)
  45.     RAW_PROC    (lowlevel access to server output)
  46.     DCC_PROC    (new /dcc commands)
  47.     WINDOW_PROC    (new /window commands)
  48.     OUTPUT_PROC    (replacement output procedure)
  49.  
  50. module name is for internal bookkeeping practices. It's displayed when we
  51. list the loaded plugins, and is also used for finding what to remove in the
  52. event of a /unloaddll. 
  53.  
  54. command name is the name of the procedure we are adding to the client. or
  55. How we will call the procedure.
  56.  
  57. description is just a description for display in a usage() function. It can
  58. be NULL as well.
  59.  
  60. id is used in a VAR_PROC HOOK_PROC and CTCP_PROC to identify some aspect of
  61. the procedure. each "type" uses id differantly. A VAR_PROC uses this to
  62. identify the type of variable being introduced ie. STR_TYPE_VAR,
  63. INT_TYPE_VAR, BOOL_TYPE_VAR. A CTCP_PROC can be set to -1. HOOK_PROC uses
  64. this to identify the hook to add this to. A negative number means this is a
  65. server numberic to add too. A non-negative value is used to indicate a
  66. particular hook. You can use the enumerated list of hooks in hook.h to make
  67. this easier ie. CHANNEL_SYNCH_LIST.
  68.  
  69. flag is used in the same procedures as id. a VAR_PROC uses this as the
  70. default INT/BOOL value for the variable. CTCP_PROC uses this to tell the
  71. client what todo when we recieve one of these ctcp's. CTCP_SPECIAL,
  72. CTCP_TELLUSER, CTCP_REPLY, CTCP_INLINE, CTCP_NOLIMIT are possible values. 
  73. These can be or'd together as well. HOOK_PROC uses this as the "noise"
  74. of this event.
  75.  
  76. function1 is the function to call for this particular command. This always
  77. needs to be supplied for all the various procedures.. Even a VAR_PROC can
  78. have a function associated with it.
  79.  
  80. function2 is the reply function for CTCP_PROC. It can be NULL.
  81.  
  82. Depending on the nature of the procedure your adding, determines what the
  83. return from that procedure should be. a $function should return a string for
  84. example. a command or a var procedure returns nothing. 
  85.  
  86. void command_proc(IrcCommandDll *, char *, char *, char *, char *);
  87.  
  88. void var_proc(Window *, char *, int);
  89.  
  90. char *alias_proc(char *);
  91.  
  92. char *ctcp_proc(CtcpEntryDll *, char *, char *, char *);
  93.  
  94. void hook_proc(int hook, char *buffer, char *);
  95. void hook_proc(char *name, char *buffer, char *);
  96.  
  97. int raw_proc(char *num, char *from, char *userhost, char **Args);
  98.  
  99. void dcc_func(char *name, char *args);
  100.  
  101. Window *window_proc(Window *, char **args, char *help);
  102.  
  103. void output_proc(Window *, const unsigned char *str);
  104.  
  105.  
  106. Tcl commands can be added from a module quite easily. Just make sure that
  107. that you call Tcl_DeleteCommand() when unloading the module. This means you
  108. need to use a Cleanup function.
  109.  
  110. A output procedure can be defined. It replaces ALL output procedures for ALL
  111. screens and windows. You will need to handle everything that the current
  112. add_to_window() function in screen.c does by yourself. You can however use
  113. any or all of the BitchX functions. When removing this procedure, ALL
  114. screens and windows are reset back to the default output procedure.
  115.  
  116.