home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / LANMAN.ZIP / PBXPKT.H < prev    next >
C/C++ Source or Header  |  1991-01-01  |  8KB  |  167 lines
  1. /*-------------------------------------------------------------------
  2.   PBXPKT.H -- PBX Protocol definitions
  3.  
  4.   Description:
  5.  
  6.   This file contains all of the constants and structures necessary
  7.   for a client to use the PBX service.  To use PBX, first:
  8.  
  9.     a) Broadcast a message on the second-class mailslot ANNOUNCELINE
  10.        with the priority of ANNOUNCEPRIORITY.  If a PBX exists on
  11.        the domain, it will respond with a message containing the
  12.        computer name of the computer on which it is executing
  13.        (prepended with two backslashes).
  14.  
  15.     b) Open the PBX named-pipe.  Construct the full UNC name by
  16.        prepending the target computer name (e.g., \\BRENDAN) to
  17.        the constant PIPELINE (usually, this will be taken from
  18.        the PBX response the broadcast in step a).
  19.  
  20.     c) Build and send as the first packet on the pipe a REGISTER
  21.        request.  This packet should contain the client name and type
  22.        (type is client dependent but cannot be zero).  If another
  23.        client of the same name and type exists, the request will be
  24.        rejected and a new name should be tried.
  25.  
  26.   After registering with PBX, you may send either LISTQUERY or
  27.   CONNECT packets to PBX.  You may also asynchronously receive a
  28.   CONNECT packet from PBX if another client requests a connection
  29.   with you.  PBX responds to all packets directed to it with an
  30.   acknowledgement by turning on the high-order bit of the usPktID
  31.   field, setting the usRetCode field, and returning the packet.
  32.  
  33.   Once two clients are connected, PBX no longer examines the data
  34.   being sent.  Instead, the data is forwarded directly to the target
  35.   client.  A connection can only be broken by one of the clients
  36.   closing their end of the named-pipe (PBX will then close the pipe
  37.   for the other client), after which both clients must re-open the
  38.   pipe and re-register with the PBX if they want to continue using
  39.   the PBX connect to other clients.
  40.  
  41.   Building PBX Packets:
  42.     ->  = Input to PBX (you must place in the packet)
  43.     <-  = Output from PBX (available in the acknowledgement packet)
  44.  
  45.   REGISTER:
  46.     PBXPKT.usPktID                  -> REGISTER
  47.     PBXPKT.usPktSize                -> sizeof(PBXPKT)
  48.     PBXPKT.usNameCnt                -> 1
  49.     PBXPKT.aPBXName[0].pszName      -> Client name
  50.     PBXPKT.aPBXName[0].usClientType -> Client program ID (should
  51.                                        identify the program using
  52.                                        PBX; it cannot be zero)
  53.  
  54.     PBXPKT.usPktID                  <- ACK | REGISTER
  55.     PBXPKT.usPktSize                <- sizeof(PBXPKT)
  56.     PBXPKT.usRetCode                <- Return code
  57.  
  58.   CONNECT :
  59.     PBXPKT.usPktID                  -> CONNECT
  60.     PBXPKT.usPktSize                -> sizeof(PBXPKT)
  61.     PBXPKT.usNameCnt                -> 1
  62.     PBXPKT.aPBXName[0].pszName      -> Target client name
  63.     PBXPKT.aPBXName[0].usClientType -> Target client program ID
  64.  
  65.     PBXPKT.usPktID                  <- ACK | CONNECT
  66.     PBXPKT.usPktSize                <- sizeof(PBXPKT)
  67.     PBXPKT.usRetCode                <- Return code
  68.  
  69.   LISTQUERY:
  70.     PBXPKT.usPktID                  -> LISTQUERY
  71.     PBXPKT.usPktSize                -> sizeof(PBXPKT)
  72.     PBXPKT.aLQNames.usFirstName     -> First name to return
  73.  
  74.     PBXPKT.usPktID                  <- ACK | LISTQUERY
  75.     PBXPKT.usPktSize                <- sizeof(PBXPKT) +
  76.                    (sizeof(PBXNAME) * PBXPKT.aLQNames.usNameCnt-1);
  77.     PBXPKT.usRetCode                <- Return code
  78.     PBXPKT.aLQNames.usNameCnt       <- Number of names returned
  79.     PBXPKT.aLQNames.fMoreNames      <- Zero or non-zero
  80.     PBXPKT.aPBXName[x].pszName      <- Client name
  81.     PBXPKT.aPBXName[x].usClientType <- Client program ID
  82.  
  83.     In a LISTQUERY acknowledgement, PBX will set
  84.     PBXPKT.aLQNames.usNameCnt to the number of names returned.
  85.     If more names exist then PBX could return,
  86.     PBXPKT.aLQNames.fMoreNames will be non-zero.  To retreive
  87.     the remaining names, send additional LISTQUERY requests setting
  88.     the PBXPKT.aLQNames.usNameCnt field to the total number of
  89.     retrieved names plus one (on the first call it should be zero).
  90.  
  91.     Because the number of names PBX may return is unknown at the
  92.     time of the call, the packet size cannot be predicted (though
  93.     it will never exceeded the pipe buffer size).  Reading a full
  94.     PBXPKT will read the first returned name, leaving
  95.     PBXPKT.aLQNames.usNameCnt-1 names in the pipe buffer.
  96.  
  97.   Author:  Brendan Dixon
  98.            Microsoft, inc.
  99.            LAN Manager Developer Support
  100.  
  101.   This code example is provided for demonstration purposes only.
  102.   Microsoft makes no warranty, either express or implied,
  103.   as to its usability in any given situation.
  104. -------------------------------------------------------------------*/
  105.  
  106. #ifndef _PBXPKTH
  107. #define _PBXPKTH
  108.  
  109. // Defines ----------------------------------------------------------
  110. #define NAMESIZE            (15+1)      // Maximum client name size
  111. #define PBXMSGSIZE          (17+1)      // Maximum PBX message size
  112.  
  113. #define PIPELINE            "\\PIPE\\MSJ\\PBX"     // PBX Named-Pipe
  114. #define ANNOUNCELINE        "\\MAILSLOT\\MSJ\\PBX" // PBX Mailslot
  115. #define ANNOUNCEPRIORITY    (9)         // PBX Message priority
  116.  
  117. // Acknowledgement return codes (returned by PBX)
  118. #define PBXERROR            1           // Unexpected PBX error
  119.  
  120. // REGISTER request return codes
  121. #define R_TOOMANYNAMES      2           // Too many names supplied
  122. #define R_NONAME            3           // No name supplied
  123. #define R_INVALIDCLIENTTYPE 4           // Client type was zero
  124. #define R_DUPLICATENAME     5           // Duplicate name in table
  125.  
  126. // CONNECT request return codes
  127. #define C_TOOMANYNAMES      2           // Too many names supplied
  128. #define C_NONAME            3           // No name supplied
  129. #define C_INVALIDNAME       4           // Invalid connection name
  130. #define C_TARGETBUSY        5           // Target client is not free
  131. #define C_TARGETERR         6           // Unable to inform target
  132.  
  133. // PBX packet identifiers
  134. #define ACK                 0x8000      // Acknowledgement bit mask
  135.  
  136. #define REGISTER            1           // Register a client
  137. #define CONNECT             2           // Connect two clients
  138. #define LISTQUERY           3           // Return list of clients
  139.  
  140. // Structures -------------------------------------------------------
  141. // PBX names structure
  142. typedef struct _PBXNAME {
  143.   char            pszName[NAMESIZE];      // Client name
  144.   unsigned short  usClientType;           // Client type
  145.                                           //   This value is client
  146.                                           //   dependent; however,
  147.                                           //   PBX reserves zero
  148. } PBXNAME;
  149.  
  150. // PBX Packet structure
  151. typedef struct _PBXPKT {
  152.   unsigned short  usPktID;                // Packet Identifer
  153.   unsigned short  usPktSize;              // Packet size
  154.   unsigned short  usRetCode;              // Return code
  155.   union {
  156.     unsigned short  usNameCnt;            // Supplied names count
  157.     struct {
  158.       unsigned short  usFirstName;        // First name to retrieve
  159.       unsigned short  usNameCnt;          // Returned names count
  160.       int             fMoreNames;         // More names exist flag
  161.     }               aLQNames;             // LISTQUERY names struct
  162.   };
  163.   PBXNAME         aPBXName[1];            // Array of PBX names
  164. } PBXPKT;
  165.  
  166. #endif
  167.