doc/api/joinbuf.txt

   1 IRC wouldn't be of much interest without the ability for users to join
   2 channels.  Of course, they must also be able to leave those channels
   3 when they get bored of the conversation there.  Users can join or
   4 leave multiple channels at once.  Sometimes these JOIN and PART
   5 messages can be ganged together into a single message.  This is
   6 facilitated by the JoinBuf system.
   7
   8 <struct>
   9 struct JoinBuf;
  10
  11 This structure is used to accumulate and describe several channel
  12 joins or parts.  None of its fields are directly or indirectly
  13 accessible to the application; a struct JoinBuf is only suitable for
  14 passing to the joinbuf_*() suite of functions.  JoinBuf structures
  15 must be allocated by the caller.
  16 </struct>
  17
  18 <macro>
  19 #define JOINBUF_TYPE_JOIN       0       /* send JOINs */
  20
  21 This macro tells joinbuf_init() that the JoinBuf is being used to
  22 generate several channel joins.
  23 </macro>
  24
  25 <macro>
  26 #define JOINBUF_TYPE_CREATE     1       /* send CREATEs */
  27
  28 This macro tells joinbuf_init() that the JoinBuf is being used to
  29 generate several channel creations.
  30 </macro>
  31
  32 <macro>
  33 #define JOINBUF_TYPE_PART       2       /* send PARTs */
  34
  35 This macro tells joinbuf_init() that the JoinBuf is being used to
  36 generate several channel parts.
  37 </macro>
  38
  39 <macro>
  40 #define JOINBUF_TYPE_PARTALL    3       /* send local PARTs, but not remote */
  41
  42 This macro tells joinbuf_init() that the JoinBuf is being used to
  43 record PARTs for all the user's channels.  That fact is communicated
  44 to servers through a more efficient means than sending several PARTs,
  45 but local clients can only be made aware of it with standard PART
  46 messages.
  47 </macro>
  48
  49 <function>
  50 void joinbuf_init(struct JoinBuf *jbuf, struct Client *source,
  51                   struct Client *connect, unsigned int type, char *comment,
  52                   time_t create);
  53
  54 This function is used to initialize a caller allocated JoinBuf,
  55 specified by _jbuf_.  The originating user is specified by _source_;
  56 the connection on which the message was received is specified by
  57 _connect_; the type (one of the JOINBUF_TYPE_* macros described above)
  58 is specified by _type_.  PART messages may have an optional comment,
  59 which is passed through the _comment_ parameter.  JOIN and CREATE
  60 messages require a timestamp, passed through the _create_ parameter.
  61 </function>
  62
  63 <function>
  64 void joinbuf_join(struct JoinBuf *jbuf, struct Channel *chan,
  65                   unsigned int flags);
  66
  67 This function adds a channel to the JoinBuf.  The _chan_ parameter
  68 specifies the channel, and may only be NULL if the JoinBuf type is
  69 JOINBUF_TYPE_JOIN--this will cause a "JOIN 0" message to be sent to
  70 all servers.  The _flags_ parameter is used to specify the user's
  71 current channel flags.  For JOINBUF_TYPE_PART and JOINBUF_TYPE_PARTALL
  72 JoinBufs, passing CHFL_ZOMBIE will inhibit sending the PART to all
  73 channel users, and CHFL_BANNED will inhibit sending the user's
  74 specified PART comment.  For JOINBUF_TYPE_JOIN or JOINBUF_TYPE_CREATE
  75 JoinBufs, the _flags_ parameter is used to set the initial channel
  76 modes for the user.
  77 </function>
  78
  79 <function>
  80 int joinbuf_flush(struct JoinBuf *jbuf);
  81
  82 This function simply flushes the contents of the struct JoinBuf to the
  83 appropriate destinations.
  84 </function>
  85
  86 <authors>
  87 Kev <klmitch@mit.edu>
  88 </authors>
  89
  90 <changelog>
  91 [2001-6-15 Kev] Initial documentation of the JoinBuf subsystem.
  92 </changelog>