home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 2 BBS / 02-BBS.zip / ad109u18.zip / adeptrexxchatfuncs.doc < prev    next >
Text File  |  1997-02-20  |  18KB  |  581 lines
  1.  
  2.                            AdeptXBBS REXX INTERFACE
  3.                           Adept v1.08x Chat Routines
  4.  
  5.                     Copyright (c) 1993 - 1996 by AdeptSoft
  6.                   portions Copyright (c)  1991-1994 M. Kimes
  7.                              All Rights Reserved
  8.  
  9.                       AdeptSoft, AdeptXBBS, GateKeeper,
  10.                         are trademarks of AdeptSoft.
  11.  
  12.       "XBBS"  Copyright (c) 1988 - 1994 by M. Kimes. The "XBBS" name is a
  13.                            Trademark of M. Kimes.
  14.                                        
  15.  
  16.  
  17. The IRC_* constants are (Note: You MUST call AdeptInitREXX first):
  18.   LOSTCARRIER if the carrier had been dropped.
  19.   IRC_NOTIMELEFT if no time is remaining.
  20.   IRC_LOCKEDOUT if the sysop locked the user out.
  21.   IRC_MORON if the system hit the moron key.
  22.   IRC_REPROMPT to request a redraw of the prompt or screen.
  23.   IRC_ENDSYSOPCHAT if the sysop broke into chat and just ended it.
  24.   IRC_IDLETIMEOUT if the user idle's out
  25.   IRC_CHATWAITING if a chat message is waiting to be processed.
  26.   IRC_CHATDOWN if the chat server went down.
  27.  
  28.  
  29.  
  30. Additional Metas:
  31.   {PQ Displays press any key to continue if the displayed amount of lines is 
  32.       more then the users screen length.
  33.   {DA Who the message was to
  34.   {DB The Message Subject
  35.   {DC Area name message was posted to
  36.   {DD Node number of receipient
  37.   {DE Area number the message was posted to
  38.   {ZZ Do not translate any metas from here until the end of the string.
  39.  
  40.  
  41.  
  42. FUNCTION LISTING
  43. ---------------------------------------------------------------------------
  44. AdeptSysChatConnectUser()
  45.  
  46.      FUNCTION USAGE
  47.        value = AdeptSysChatConnectUser(LineNumber)
  48.  
  49.      ARGUMENTS
  50.        LineNumber: 
  51.        Node Number passed to REXX routine from Adept as first parameter. 
  52.  
  53.      RETURNED VALUE
  54.        0 - Syntax error
  55.        1 - User connected with server
  56.        2 - Failed to connect user to server
  57.        3 - Server unavailable
  58.  
  59.      DESCRIPTION
  60.        Will connect/sign up a user with the chat server.
  61.  
  62.      NOTES
  63.         
  64.      EXAMPLE
  65.      The next example will attempt to connect the user to the chatserver,
  66.      if it succeeds it will join the user to the main conference.  If not,
  67.      the script will notify the user that the server is down and exit the
  68.      script.
  69.  
  70.      RetC = AdeptSysChatConnectUser(line)
  71.  
  72.      if(RetC == 1) then do
  73.        RetC = AdeptSysChatJoinConf(line, "Main")
  74.      end
  75.      else do
  76.        AdeptPrint(line, "\r\n\nChat server unavailable\r\n{PC")
  77.        exit
  78.      end
  79.   
  80.      RELATED FUNCTIONS
  81.        AdeptSysChatReconnectUser()
  82.        AdeptSysChatUserConnected()
  83.  
  84. ---------------------------------------------------------------------------
  85. AdeptSysChatCustomMsg()
  86.  
  87.      FUNCTION USAGE
  88.        call AdeptSysChatCustomMsg LineNumber, PktType, To, Message
  89.        or
  90.        value = AdeptSysChatCustomMsg(LineNumber, PktType, To, Message)
  91.  
  92.      ARGUMENTS
  93.        LineNumber: 
  94.        Node Number passed to REXX routine from Adept as first parameter. 
  95.  
  96.        PktType:
  97.        Packet Type.  Must be greater than 1000.
  98.  
  99.        To:
  100.        User Name to send custom message to.
  101.               or
  102.                 -1 - All users in the current channel
  103.                 -2 - All users on the BBS (Not currently supported)
  104.                 -3 - All users on the chatserver (Not currently supported)
  105.                 -4 - All local ops (Not currently supported)
  106.                 -5 - All server ops (Not currently supported)
  107.  
  108.        Message:
  109.        Message to send.
  110.  
  111.      RETURNED VALUE
  112.        0 - Syntax error
  113.        1 - Sent to server
  114.  
  115.      DESCRIPTION
  116.        AdeptSysChatCustomMsg allows you to send messages to the user that 
  117.        you can parse via the rexx AdeptSysChatGetMsg.  This allows you to
  118.        add new chat options, functions and types.
  119.  
  120.      NOTES
  121.        You cannot specify a type below 1000, all types MUST begin with 
  122.        1001 or higher, the bottom 1000 are reseved for system use.  
  123.        You can have fun with this.
  124.         
  125.      EXAMPLE
  126.        This example will alert everyone in the channel that the user has 
  127.        left the channel and exit the user from the channel.
  128.  
  129.        Leave:
  130.          Parse Arg Reason
  131.  
  132.          rc = AdeptSysChatPubMsg(Line, '{FG« {FF' || UserName || ' has Left the Channel!')
  133.          rc = AdeptSysChatCustomMsg(Line, 1002, -1, 'Leave')
  134.          rc = AdeptSysChatLeaveConf(Line)
  135.        Return
  136.   
  137.      RELATED FUNCTIONS
  138.        AdeptSysChatGetMsg()
  139.  
  140. ---------------------------------------------------------------------------
  141. AdeptSysChatGetMsg()
  142.  
  143.      FUNCTION USAGE
  144.        value = AdeptSysChatGetMsg(LineNumber)
  145.  
  146.      ARGUMENTS
  147.        LineNumber: 
  148.        Node Number passed to REXX routine from Adept as first parameter. 
  149.  
  150.      RETURNED VALUE
  151.        0 - Didn't receive a packet or bad packet
  152.        1 - Received a chat packet that does NOT have a chatmsg attached
  153.        2 - Received a chat packet that does have a chatmsg attached
  154.        3 - Received a chat packet that does have a chatmsg with a chat 
  155.            data packet attached.
  156.  
  157.      DESCRIPTION
  158.        You call this when you receive a IRC_CHATWAITING.  It will return a
  159.        value according to the table above and may assign values to a number
  160.        of variables (detailed below)
  161.  
  162.      NOTES
  163.        The variables are:
  164.  
  165.        The following are set if the return code is 1
  166.  
  167.          PKTTYPE   - Packet type definitions follow.
  168.            100 - Standard Public Conference Message
  169.            101 - No Prepended Public Conference Message
  170.            102 - Private message to another user/node
  171.            103 - Invite a user to a channel
  172.            104 - Leave chat
  173.            105 - System Global Message to all no matter where
  174.  
  175.          PKTSERIAL - Packet Serial Number (Currently the time it was sent)
  176.          PKTCRC    - 32 bit CRC of the ChatMsg if one it to be sent for
  177.                      validation of the chat message.
  178.  
  179.        The following are also set if the return code is 2
  180.  
  181.          CHATMSGFROM     - User or Node number the chat message was from.
  182.          CHATMSGFLAGS    - Flags for the message (Currently unused)
  183.          CHATMSGSCRAMBLE - Scramble code for the message, I.E. Only those 
  184.                            with the same code set can see it.
  185.          CHATMSGTO       - Who the message is to.  If blank, it's considered 
  186.                            to be a public style message for use public chat.
  187.  
  188.        The following are also set if the return code is 3
  189.  
  190.          CHATMSGDATALEN  - Length of the data.
  191.          CHATMSGDATACRC  - CRC of the Data.
  192.          CHATMSGDATA     - The data, usually the chat messages text, could 
  193.                            be binary if you so desire.  4k limit.
  194.         
  195.      EXAMPLE
  196.        if(AdeptSysChatMsgWaiting(line) == 1)then
  197.        do
  198.          RetC = AdeptSysChatGetMsg(line)
  199.  
  200.          if(RetC == 2) then do
  201.            if(PktType == 103) then do
  202.              AdeptPrint(line, "\rUser "||CHATMSGFROM||" invited you to chat!\r\n")
  203.              return 0
  204.            end
  205.          end
  206.        end
  207.   
  208.      RELATED FUNCTIONS
  209.        AdeptSysChatCustomMsg()
  210.  
  211. ---------------------------------------------------------------------------
  212. AdeptSysChatInput()
  213.  
  214.      FUNCTION USAGE
  215.        call AdeptSysChatInput LineNumber, "BufferName", AbortKeyList, 
  216.                               InputText
  217.        or
  218.        value = AdeptSysChatInput(LineNumber, "BufferName", AbortKeyList, 
  219.                                  InputText)
  220.  
  221.      ARGUMENTS
  222.        LineNumber: 
  223.        Node Number passed to REXX routine from Adept as first parameter.
  224.  
  225.        BufferName:
  226.        Variable to place the text in.
  227.  
  228.        AbortKeyList:
  229.        AbortKeyList is a optional command.  If you don't pass it a keylist 
  230.        and the user presses enter on a line it will return 1, if you pass 
  231.        it a keylist and the user presses enter it will return 1, for all 
  232.        other keys pressed it will return their ascii value.
  233.  
  234.        The keylist should not contain the ascii numeric value for a key 
  235.        but the actual ascii key itself.  (ie. Ascii 3, ^C would be a heart.)
  236.  
  237.        InputText:
  238.        If InputText is passed it will place it in the users buffer as if they
  239.        had typed it.  They can backspace over it and delete the text passed
  240.        to the buffer.
  241.  
  242.      RETURNED VALUE
  243.        The above function will return 1 if all is well and the user pressed
  244.        return.   It can also return any of the IRC_* constants.
  245.  
  246.      DESCRIPTION
  247.        A function very similiar to AdeptInput except specificly designed to
  248.        be used with multi-node chat.
  249.  
  250.      NOTES
  251.        AbortKeyList and InputText are optional, you don't need to pass them
  252.        for AdeptSysChatInput to work.
  253.         
  254.      EXAMPLE
  255.        This example will input a chat line from the user into UserText to be
  256.        parsed and output appropriatly later.
  257.  
  258.        RetC = AdeptSysChatInput(line, "USERTEXT", KeyList)
  259.   
  260.      RELATED FUNCTIONS
  261.  
  262. ---------------------------------------------------------------------------
  263. AdeptSysChatJoinConf()
  264.  
  265.      FUNCTION USAGE
  266.        call AdeptSysChatJoinConf LineNumber, ConferenceName
  267.        or
  268.        value = AdeptSysChatJoinConf(LineNumber, ConferenceName)
  269.  
  270.      ARGUMENTS
  271.        LineNumber: 
  272.        Node Number passed to REXX routine from Adept as first parameter. 
  273.  
  274.        ConferenceName:
  275.        Name of conference to join user to.
  276.  
  277.      RETURNED VALUE
  278.        0 - Join Not Successful
  279.        1 - Access Denied to Channel
  280.        2 - Channel Joined
  281.  
  282.      DESCRIPTION
  283.        Joins the user to a chat conference.
  284.  
  285.      NOTES
  286.         
  287.      EXAMPLE
  288.       This example will attempt to join the user to a conference named Main.
  289.       It will exit the script if the attempt was unsuccessful.
  290.  
  291.       rc = AdeptSysChatJoinConf(line, "Main")
  292.       if(rc<>2)then
  293.       do
  294.         Call AdeptPrint line, "I'm sorry.  Could not join conference!"
  295.         exit
  296.       end
  297.   
  298.      RELATED FUNCTIONS
  299.        AdeptSysChatLeaveConf()
  300.  
  301. ---------------------------------------------------------------------------
  302. AdeptSysChatLeaveConf()
  303.  
  304.      FUNCTION USAGE
  305.        AdeptSysChatLeaveConf(LineNumber)
  306.  
  307.      ARGUMENTS
  308.        LineNumber: 
  309.        Node Number passed to REXX routine from Adept as first parameter. 
  310.  
  311.      RETURNED VALUE
  312.        Returns 1 every time.
  313.  
  314.      DESCRIPTION
  315.        If the user is in a conference it will remove the user from the 
  316.        conference.
  317.  
  318.      NOTES
  319.         
  320.      EXAMPLE
  321.      This example will notify other users and then leave the current 
  322.      conference.
  323.  
  324.      if(Command == '/Q' | Command == '/E') then do
  325.        SendString = '{FE[{FG' || UserNode || '{F8-{FB' || UserName || '{FE] {FC{ZZ' || 'Leaving...'
  326.        call AdeptSysChatPubMsg line, SendString
  327.        call AdeptSysChatLeaveConf line
  328.        exit
  329.      end
  330.   
  331.      RELATED FUNCTIONS
  332.        AdeptSysChatJoinConf()
  333.  
  334. ---------------------------------------------------------------------------
  335. AdeptSysChatMessageWaiting()
  336.  
  337.      FUNCTION USAGE
  338.        value = AdeptSysChatMessageWaiting(LineNumber)
  339.  
  340.      ARGUMENTS
  341.        LineNumber: 
  342.        Node Number passed to REXX routine from Adept as first parameter. 
  343.  
  344.      RETURNED VALUE
  345.        0 - Syntax Error
  346.        1 - There is a chat message waiting
  347.        2 - Error User Not Connected
  348.        3 - Error Server is Down
  349.  
  350.      DESCRIPTION
  351.        Checks to see if the User on LineNumber has a chat message waiting.
  352.  
  353.      NOTES
  354.         
  355.      EXAMPLE
  356.        do while(AdeptSysChatMsgWaiting(line) == 1)
  357.          RetC = AdeptSysChatGetMsg(line)
  358.          .
  359.          .
  360.          /* Deal misc different pkttypes etc. */
  361.          .
  362.          .
  363.        end
  364.   
  365.      RELATED FUNCTIONS
  366.  
  367. ---------------------------------------------------------------------------
  368. AdeptSysChatMsg()
  369.  
  370.      FUNCTION USAGE
  371.        Call AdeptSysChatMsg LineNumber, Text
  372.  
  373.      ARGUMENTS
  374.        LineNumber: 
  375.        Node Number passed to REXX routine from Adept as first parameter. 
  376.  
  377.        Text:
  378.        Message to send to user.
  379.  
  380.      RETURNED VALUE
  381.  
  382.      DESCRIPTION
  383.        Sends a chat message to a user.
  384.  
  385.      NOTES
  386.        You format how the text is to be displayed to the remote user.  
  387.        Please use the {COLOR metas or ascii users will get ansi if you 
  388.        put ANSI escape characters etc in the text.
  389.  
  390.        This can be used for annoucements such as User so and so has logged 
  391.        on via node such and such.  Be creative.
  392.         
  393.      EXAMPLE
  394.   
  395.      RELATED FUNCTIONS
  396.  
  397. ---------------------------------------------------------------------------
  398. AdeptSysChatPrivMsg()
  399.  
  400.      FUNCTION USAGE
  401.        Call AdeptSysChatPrivMsg LineNumber, Node, MessageText
  402.        or
  403.        value = AdeptSysChatPrivMsg(LineNumber, Node, MessageText)
  404.  
  405.      ARGUMENTS
  406.        LineNumber: 
  407.        Node Number passed to REXX routine from Adept as first parameter. 
  408.  
  409.        Node:
  410.        Node Number to send the message to.
  411.  
  412.        MessageText:
  413.        Message Text.
  414.  
  415.      RETURNED VALUE
  416.        0 - Message wasn't sucessfully sent
  417.        1 - Message was sent
  418.  
  419.      DESCRIPTION
  420.        Sends a private chat message to a specified node number.
  421.  
  422.      NOTES
  423.        If the user is not on a particular node the message will go into 
  424.        limbo.
  425.         
  426.      EXAMPLE
  427.        This example will send a private message contained in MsgText to the
  428.        user on node NodeTo.
  429.  
  430.        SendString = '{FE[{FG' || UserNode || '{F8-{FB' || UserName || '{FD, Pvt Msg{FE] {FC{ZZ' || MsgText
  431.        call AdeptSysChatPrivMsg line, NodeTo, SendString
  432.   
  433.      RELATED FUNCTIONS
  434.        AdeptSysChatPubMsg()
  435.  
  436. ---------------------------------------------------------------------------
  437. AdeptSysChatPubMsg()
  438.  
  439.      FUNCTION USAGE
  440.        call AdeptSysChatPubMsg LineNumber, MessageText
  441.        value = AdeptSysChatPubMsg(LineNumber, MessageText)
  442.  
  443.      ARGUMENTS
  444.        LineNumber: 
  445.        Node Number passed to REXX routine from Adept as first parameter. 
  446.  
  447.        MessageText:
  448.        Message Text.
  449.  
  450.      RETURNED VALUE
  451.        0 - Message wasn't sucessfully sent misc error
  452.        1 - Message was sent
  453.  
  454.      DESCRIPTION
  455.        Send a public message in the current conference.
  456.  
  457.      NOTES
  458.        The user must be a in a conference for others to see the message or 
  459.        it will just go into limbo.
  460.         
  461.      EXAMPLE
  462.        The following example will announce to the current conference that you
  463.        have entered.
  464.  
  465.        SendString = '{FE[{FG' || UserNode || '{F8-{FB' || UserName || '{FE] {FC{ZZ' || 'Entering...'
  466.        AdeptSysChatPubMsg(line, SendString)
  467.   
  468.      RELATED FUNCTIONS
  469.        AdeptSysChatPrivMsg()
  470.  
  471. ---------------------------------------------------------------------------
  472. AdeptSysChatReconnectUser()
  473.  
  474.      FUNCTION USAGE
  475.        value = AdeptSysChatReconnectUser(LineNumber)
  476.  
  477.      ARGUMENTS
  478.        LineNumber: 
  479.        Node Number passed to REXX routine from Adept as first parameter. 
  480.  
  481.      RETURNED VALUE
  482.        0 - Syntax error
  483.        1 - User connected to server
  484.        2 - Failed to reconnect user
  485.        3 - Sever not available
  486.  
  487.      DESCRIPTION
  488.        Reconnects a user to the chatserver.
  489.  
  490.      NOTES
  491.        AdeptSysChatReconnectUser() should only be used to reconnect a 
  492.        user to the chatserver after it has gone down and the user was 
  493.        chatting in a conference.
  494.         
  495.      EXAMPLE
  496.        The following example will attempt to reconnect to the chatserver if
  497.        it detects that the chatserver has gone down.  If the reconnection 
  498.        fails, It will exit the conference then exit the script.
  499.  
  500.        if(RetC == IRC_CHATDOWN) then do
  501.          RetC = AdeptSysChatReconnectUser(line)
  502.          if(RetC \= 1) then do
  503.            call AdeptSysChatLeaveConf line
  504.            exit
  505.          end
  506.        end
  507.   
  508.      RELATED FUNCTIONS
  509.        AdeptSysChatConnectUser()
  510.        AdeptSysChatUserConnected()
  511.  
  512. ---------------------------------------------------------------------------
  513. AdeptSysChatUserConnected()
  514.  
  515.      FUNCTION USAGE
  516.        value = AdeptSysChatUserConnected(LineNumber)
  517.  
  518.      ARGUMENTS
  519.        LineNumber: 
  520.        Node Number passed to REXX routine from Adept as first parameter. 
  521.  
  522.      RETURNED VALUE
  523.        0 - Syntax Error
  524.        1 - User connected
  525.        2 - User not connected
  526.        3 - Server down, obviosly the user is not connected.
  527.  
  528.      DESCRIPTION
  529.        Checks to make sure the user is properly connected to the chat 
  530.        server.
  531.  
  532.      NOTES
  533.         
  534.      EXAMPLE
  535.        This example will try to reconnect to the chatserver.  If it fails it
  536.        will exit the script.
  537.  
  538.        call AdeptSysChatReconnectUser line
  539.        RetC = AdeptSysChatUserConnected(line)
  540.  
  541.        if(RetC \= 1) then do
  542.          call AdeptPrint line, "\rCould not reconnect to chat server, exiting...\r\n"
  543.          exit
  544.        end
  545.        else do
  546.          call AdeptPrint line, "\rChat server reconnected, you may continue to chat.\r\n"
  547.        end
  548.   
  549.      RELATED FUNCTIONS
  550.        AdeptSysChatConnectUser()
  551.        AdeptSysChatReconnectUser()
  552.  
  553. ---------------------------------------------------------------------------
  554. AdeptSysCheckForServer()
  555.  
  556.      FUNCTION USAGE
  557.        value = AdeptSysCheckForServer(LineNumber)
  558.  
  559.      ARGUMENTS
  560.        LineNumber: 
  561.        Node Number passed to REXX routine from Adept as first parameter. 
  562.  
  563.      RETURNED VALUE
  564.        0 - Syntax error
  565.        1 - Server not available
  566.        2 - Server available
  567.  
  568.      DESCRIPTION
  569.        Checks to make sure the chat server is available.
  570.  
  571.      NOTES
  572.         
  573.      EXAMPLE
  574.   
  575.      RELATED FUNCTIONS
  576.  
  577. ---------------------------------------------------------------------------
  578. ***       End Of AdeptXBBS AdeptRexx v1.08x ChatServer Functions.       ***
  579. ---------------------------------------------------------------------------
  580. 
  581.