home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / perl502b.zip / ext / DPI / snmp_dpi.h < prev    next >
C/C++ Source or Header  |  1995-09-26  |  40KB  |  718 lines
  1. /*
  2. \begin{verbatim}
  3. */
  4.  
  5. #ifndef snmp_dpiH
  6. #define snmp_dpiH
  7.  
  8. /*********************************************************************/
  9. /*                                                                   */
  10. /* SNMP-DPI API - SNMP Distributed Protocol Interface                */
  11. /*                Application Programming Interface                  */
  12. /*                                                                   */
  13. /* Oct 27, 1994 - Version 0.14i                                      */
  14. /*                                                                   */
  15. /* Copyright    - (C) International Business Machines Corp. 1994     */
  16. /*                                                                   */
  17. /*   Permission to use, copy, modify, and distribute this software   */
  18. /*   and its documentation for any lawful purpose and without fee is */
  19. /*   hereby granted, provided that this notice be retained unaltered,*/
  20. /*   and that the names of IBM and all other contributors shall not  */
  21. /*   be used in advertising or publicity pertaining to distribution  */
  22. /*   of the software without specific written prior permission.      */
  23. /*   No contributor makes any representations about the suitability  */
  24. /*   of this software for any purpose.  It is provided "as is"       */
  25. /*   without express or implied warranty.                            */
  26. /*                                                                   */
  27. /*   IBM AND ALL OTHER CONTRIBUTORS DISCLAIM ALL WARRANTIES WITH     */
  28. /*   REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF    */
  29. /*   MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, TITLE,    */
  30. /*   AND NON-INFRINGEMENT.                                           */
  31. /*                                                                   */
  32. /*   IN NO EVENT SHALL IBM OR ANY OTHER CONTRIBUTOR BE LIABLE FOR    */
  33. /*   ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, WHETHER IN      */
  34. /*   CONTRACT, TORT, OR OTHER FORM OF ACTION, ARISING OUT OF OR IN   */
  35. /*   CONNECTION WITH, THE USE OR PERFORMANCE OF THIS SOFTWARE.       */
  36. /*                                                                   */
  37. /* snmp_dpi.h   - Base include file for SNMP DPI subagent support    */
  38. /*              - This file defines the DPI interface for the DPI    */
  39. /*                subagent programmer. This interface should be the  */
  40. /*                same on all platforms and in all implementations   */
  41. /*                                                                   */
  42. /*********************************************************************/
  43.  
  44. /* Change activitity:
  45.  *
  46.  * $Log: snmp_dpi.h,v $
  47.  * Revision 3.0  1995/04/05  21:30:00  snmpdev
  48.  * new level for snmpv2 development
  49.  *
  50.  * Revision 2.9  1995/04/05  21:29:17  snmpdev
  51.  * rfc1440 freeze
  52.  *
  53.  * Revision 2.0  1994/10/29  01:18:36  pederson
  54.  * Revision 2.0
  55.  *
  56.  *
  57.  */
  58.  
  59. #pragma pack(4)
  60.  
  61. /*********************************************************************/
  62. /* Some of the compilers we used want a special LINKAGE keyword for  */
  63. /* functions so they can do compiler independent linking. So we can  */
  64. /* accomodate for that with e LINKAGE definition that is a no-op by  */
  65. /* default. Specifically OS/2 needs this.                            */
  66. /*********************************************************************/
  67. #ifndef LINKAGE
  68. #if defined(OS2) | defined(__OS2__)       /* for OS/2 we must define */
  69. #define LINKAGE  _System                  /* _System Linkage because */
  70. #else  /* not OS2 */                      /* DLLs/LIBs use that, else*/
  71. #define LINKAGE                           /* don't show to compiler  */
  72. #endif /* OS2 */                         
  73. #endif /* ndef LINKAGE */
  74.  
  75. /*********************************************************************/
  76. /* Some of the compilers we used seem to have trouble with the const */
  77. /* qualifier (or I do not understand yet all its implications).      */
  78. /* Anyways, I have used CONST qualifier where I want to use const.   */
  79. /* If you compile with the -DCONST option, then the const qualifier  */
  80. /* is used. Otherwise, it is just ignored.                           */
  81. /*********************************************************************/
  82. #ifdef CONST
  83. #  ifndef CONST_ALREADY_DEFINED  /* CONST not defined in other h file*/
  84. #    undef CONST                          /* undo and define our way */
  85. #    define CONST const                   /* show it to compiler     */
  86. #    define CONST_ALREADY_DEFINED  /* indicate CONST defined         */
  87. #  endif
  88. #else
  89. #  define CONST                           /* don't show compiler     */
  90. #  define CONST_ALREADY_DEFINED    /* indicate CONST defined         */
  91. #endif
  92.  
  93. /*********************************************************************/
  94. /* This is the size of the (static) buffer in which DPI packets are  */
  95. /* created by the mkDPIxxxx functions. The variable is defined here  */
  96. /* so that DPI subagent programmers can inspect it.                  */
  97. /*********************************************************************/
  98. #ifndef SNMP_DPI_BUFSIZE
  99. #define SNMP_DPI_BUFSIZE    4096       /* max size of a DPI packet   */
  100. #endif
  101.  
  102. /*********************************************************************/
  103. /* These are options still under discussion for DPI 2.0              */
  104. /* But for time being they are included.                             */
  105. /*********************************************************************/
  106. #define SNMP_DPI_VIEW_SELECTION
  107. #define SNMP_DPI_BULK_SELECTION
  108. /*#define SNMP_DPI_REGISTER_WITH_COMMUNITY*//* removed in revision 5 */
  109.  
  110. /*********************************************************************/
  111. /* These are the codes for the SNMP_DPI packet types.                */
  112. /* They come from RFC 1228 plus DPI 2.0 additions as defined in the  */
  113. /* RFC 1592 for DPI version 2.0                                      */
  114. /*********************************************************************/
  115. #define SNMP_DPI_GET            1
  116. #define SNMP_DPI_GETNEXT        2
  117. #define SNMP_DPI_SET            3
  118. #define SNMP_DPI_TRAP           4
  119. #define SNMP_DPI_TRAPV1         4      /* is the same as TRAP        */
  120. #define SNMP_DPI_RESPONSE       5
  121. #define SNMP_DPI_REGISTER       6
  122. #define SNMP_DPI_UNREGISTER     7
  123. #define SNMP_DPI_OPEN           8
  124. #define SNMP_DPI_CLOSE          9
  125. #define SNMP_DPI_COMMIT        10
  126. #define SNMP_DPI_UNDO          11
  127. #define SNMP_DPI_GETBULK       12
  128. #define SNMP_DPI_TRAPV2        13      /* reserved, not implemented  */
  129. #define SNMP_DPI_INFORM        14      /* reserved, not implemented  */
  130. #define SNMP_DPI_ARE_YOU_THERE 15
  131.  
  132. /*********************************************************************/
  133. /* If a user a DPI subagent programmer wants to use an older level   */
  134. /* of the DPI protocol, then he/she can specify that in his source   */
  135. /* by these C-preprocessor define statements:                        */
  136. /*   #define SNMP_DPI_VERSION 1                                      */
  137. /*   #define SNMP_DPI_RELEASE 1        ** or 0 is also valid         */
  138. /* This may be useful when you want to use existing DPI subagent     */
  139. /* code with the DPI 2.0 library and include files.                  */
  140. /* The default is Version 2 Release 0.                               */
  141. /*********************************************************************/
  142. #define SNMP_DPI_PROTOCOL   2          /* This is SNMP-DPI protocol  */
  143. #ifndef SNMP_DPI_VERSION               /* if user did not specify a  */
  144. #define SNMP_DPI_VERSION    2          /* version, then default is 2 */
  145. #endif
  146. #ifndef SNMP_DPI_RELEASE               /* if user did not specify a  */
  147. #define SNMP_DPI_RELEASE    0          /* release, then default is 0 */
  148. #endif
  149.  
  150. #if (SNMP_DPI_VERSION == 1)            /* if caller wants DPI 1.x    */
  151.  
  152. #include "snmp_dp1.h"                  /* compatibility, include it  */
  153.  
  154. #else /* no SNMP_DPI_VERSION 1 */      /* else define them for 2.x   */
  155.  
  156. #define mkDPIAreYouThere       mkDPIayt
  157. #define mkDPIregister(a,b,c,d) mkDPIreg((a),(b),(c),(d),0)
  158. #define mkDPIunregister(a,b)   mkDPIureg((a),(b))
  159. #define mkDPIresponse(a,b,c,d) mkDPIresp((a),(b),(c),(d))
  160. #define mkDPItrap(a,b,c,d)     mkDPItrape((a),(b),(c),(d))
  161. #define mkDPIget(a,b,c)        mkDPIget_packet((a),(b),(c))
  162. #define mkDPIset(a,b,c,d,e,f)  mkDPIset_packet((a),(b),(c),(d),(e),(f))
  163. #define mkDPInext(a,b,c)       mkDPInext_packet((a),(b),(c))
  164. #define fDPIset(a)             fDPIset_packet((a))
  165. #define query_DPI_port(a,b,c)  qDPIport((a),(b),(c))
  166. #define DPI_PACKET_LEN(packet) (((packet) == (void *)0) ? 0 : \
  167.                                (*((unsigned char *)(packet)) * 256 + \
  168.                                  *(((unsigned char *)(packet))+1)) + 2 )
  169.  
  170. #endif /* (SNMP_DPI_VERSION == 1) */
  171.  
  172. #ifdef DPI_INCLUDE_SNMP_CONFIG
  173. #include "snmp_config.h"
  174. #endif
  175.  
  176. /*********************************************************************/
  177. /* SNMP_DPI variable types from RFC1592 for SNMP DPI Version 2.0     */
  178. /* - The 32-bit numeric-type TYPEs have the high order bit set so    */
  179. /*   you can quickly check for a 4-byte numeric value.               */
  180. /*   These have their value in the DPI packet in network byte order  */
  181. /*   (MSB first, LSB last), but they have the value in host byte     */
  182. /*   order when passed as arguments to functions or when present in  */
  183. /*   a parse tree. So a DPI sub-agent programmer when using the API  */
  184. /*   need not be concerned with the byte order in the DPI packet.    */
  185. /* - Counter 64 is currently implemented such that the the value is  */
  186. /*   in 8-byte, network byte order in the DPI packet and that the    */
  187. /*   value pointed to by the snmp_dpi_set_structure is a ptr to a    */
  188. /*   snmp_dpi_u64 structure that has 2 unsigned long integers, one   */
  189. /*   for the high order (Most significant) and one for the low order */
  190. /*   (Least significant) 32-bit pieces. The DPI sub-agent programmer */
  191. /*   need only be concerned with the snmp_dpi_u64 structure.         */
  192. /* - Beware that Textual Conventions are not known on the wire       */
  193. /*   (in SNMP PDUs), so that is why we do not provide types for them.*/
  194. /*   You must use the base type in which the data is represented.    */
  195. /*   The one exception is a DisplayString. If the agent knows the    */
  196. /*   textual convention of an object to be DisplayString (from some  */
  197. /*   form of a compiled MIB), then it passes SNMP_TYPE_DisplayString */
  198. /*   The reason for this is that DisplayString is special in the     */
  199. /*   sense that it often used to determine how to print/display the  */
  200. /*   data (always printable).                                        */
  201. /* - Values for DisplayString and OBJECT_IDENTIFIERS are represented */
  202. /*   as strings in the character set selected at DPI OPEN time.      */
  203. /* - In DPI 1.x the IP address was (128|5), and now it is just 5.    */
  204. /*   In both cases it is an IP address, 4 bytes, network byte order. */
  205. /*   The high order bit (128) should not have been used in DPI 1.x   */
  206. /* - It is recommended to use these DPI 2.0 names for SNMP_TYPE_xxxx */
  207. /*   They are based on the names used in SNMPv2 (RFC1442)            */
  208. /* - The BIT_STRING is currently implemented such that you get an    */
  209. /*   octet string of the form 0xuubbbb....bb where the first octet   */
  210. /*   uu has a value in the range 0-7 indicating how many unused bits */
  211. /*   there are in the last byte bb. The bb bytes represent the bit   */
  212. /*   string itself, where bit zero (0) comes fist and so on. This is */
  213. /*   the case both in the DPI packet and in the snmp_dpi_set_packet  */
  214. /*   structure.                                                      */
  215. /*********************************************************************/
  216. #define SNMP_TYPE_MASK           0x7f  /* mask to isolate type       */
  217. #define SNMP_TYPE_Integer32    (128|1) /* 32-bit INTEGER             */
  218. #define SNMP_TYPE_OCTET_STRING      2  /* OCTET STRING (ASN.1)       */
  219. #define SNMP_TYPE_OBJECT_IDENTIFIER 3  /* OBJECT IDENTIFIER (ASN.1)  */
  220. #define SNMP_TYPE_NULL              4  /* NULL (ASN.1)               */
  221. #define SNMP_TYPE_IpAddress         5  /* IMPLICIT OCTET STRING (4)  */
  222. #define SNMP_TYPE_Counter32    (128|6) /* 32-bit Counter (unsigned)  */
  223. #define SNMP_TYPE_Gauge32      (128|7) /* 32-bit Gauge   (unsigned)  */
  224. #define SNMP_TYPE_TimeTicks    (128|8) /* 32-bit TimeTicks (unsigned)*/
  225.                                        /* in hundreths of a second   */
  226. #define SNMP_TYPE_DisplayString     9  /* DisplayString (Textual Con)*/
  227. #define SNMP_TYPE_BIT_STRING        10 /* BIT STRING (ASN.1)         */
  228. #define SNMP_TYPE_NsapAddress       11 /* IMPLICIT OCTET STRING      */
  229. #define SNMP_TYPE_UInteger32   (128|12)/* 32-bit INTEGER (unsigned)  */
  230. #define SNMP_TYPE_Counter64         13 /* 64-bit Counter (unsigned)  */
  231. #define SNMP_TYPE_Opaque            14 /* IMPLICIT OCTET STRING      */
  232. #define SNMP_TYPE_noSuchObject      15 /* IMPLICIT NULL              */
  233. #define SNMP_TYPE_noSuchInstance    16 /* IMPLICIT NULL              */
  234. #define SNMP_TYPE_endOfMibView      17 /* IMPLICIT NULL              */
  235.  
  236. /*********************************************************************/
  237. /* These codes should be used in the ret_code field of an SNMP DPI   */
  238. /* reponse packet. There are 2 types of error codes:                 */
  239. /* - Error codes as defined in RFC1448, section 3, page 9. These are */
  240. /*   to be used when sending a response to an original SNMP request  */
  241. /*   (e.g. GET, GETNEXT, SET, COMMIT, UNDO).                         */
  242. /* - Additional SNMP DPI error codes, to be used for responses to    */
  243. /*   DPI specific requests (e.g. OPEN, REGISTER, UNREGISTER).        */
  244. /*********************************************************************/
  245. #ifndef snmp_baseH
  246. #define SNMP_ERROR_noError             0
  247. #define SNMP_ERROR_tooBig              1
  248. #define SNMP_ERROR_noSuchName          2
  249. #define SNMP_ERROR_badValue            3
  250. #define SNMP_ERROR_readOnly            4
  251. #define SNMP_ERROR_genErr              5
  252. #define SNMP_ERROR_noAccess            6
  253. #define SNMP_ERROR_wrongType           7
  254. #define SNMP_ERROR_wrongLength         8
  255. #define SNMP_ERROR_wrongEncoding       9
  256. #define SNMP_ERROR_wrongValue          10
  257. #define SNMP_ERROR_noCreation          11
  258. #define SNMP_ERROR_inconsistentValue   12
  259. #define SNMP_ERROR_resourceUnavailable 13
  260. #define SNMP_ERROR_commitFailed        14
  261. #define SNMP_ERROR_undoFailed          15
  262. #define SNMP_ERROR_authorizationError  16
  263. #define SNMP_ERROR_notWritable         17
  264. #define SNMP_ERROR_inconsistentName    18
  265. #endif /* ndef snmp_baseH */
  266.  
  267. #define SNMP_ERROR_DPI_noError                             0
  268. #define SNMP_ERROR_DPI_otherError                        101
  269. #define SNMP_ERROR_DPI_notFound                          102
  270. #define SNMP_ERROR_DPI_alreadyRegistered                 103
  271. #define SNMP_ERROR_DPI_higherPriorityRegistered          104
  272. #define SNMP_ERROR_DPI_mustOpenFirst                     105
  273. #define SNMP_ERROR_DPI_notAuthorized                     106
  274. #define SNMP_ERROR_DPI_viewSelectionNotSupported         107
  275. #define SNMP_ERROR_DPI_getBulkSelectionNotSupported      108
  276. #define SNMP_ERROR_DPI_duplicateSubAgentIdentifier       109
  277. #define SNMP_ERROR_DPI_invalidDisplayString              110
  278. #define SNMP_ERROR_DPI_characterSetSelectionNotSupported 111
  279.  
  280. /*********************************************************************/
  281. /* SNMP DPI UNREGISTER reason codes                                  */
  282. /*********************************************************************/
  283. #define SNMP_UNREGISTER_otherReason                1
  284. #define SNMP_UNREGISTER_goingDown                  2
  285. #define SNMP_UNREGISTER_justUnregister             3
  286. #define SNMP_UNREGISTER_newRegistration            4
  287. #define SNMP_UNREGISTER_higherPriorityRegistered   5
  288. #define SNMP_UNREGISTER_byManager                  6
  289. #define SNMP_UNREGISTER_timeout                    7
  290.  
  291. /*********************************************************************/
  292. /* SNMP DPI CLOSE reason codes                                       */
  293. /*********************************************************************/
  294. #define SNMP_CLOSE_otherReason                     1
  295. #define SNMP_CLOSE_goingDown                       2
  296. #define SNMP_CLOSE_unsupportedVersion              3
  297. #define SNMP_CLOSE_protocolError                   4
  298. #define SNMP_CLOSE_authenticationFailure           5
  299. #define SNMP_CLOSE_byManager                       6
  300. #define SNMP_CLOSE_timeout                         7
  301. #define SNMP_CLOSE_openError                       8
  302.  
  303. /*********************************************************************/
  304. /* These are structures for a (partial) parse tree for DPI packets.  */
  305. /*********************************************************************/
  306. struct dpi_reg_packet {
  307.   unsigned short          timeout;     /* in seconds; 16-bit u_int   */
  308.   long int                priority;    /* priority for this subagent */
  309.   char                   *group_p;     /* ptr to group OIDstring     */
  310.   struct dpi_reg_packet  *next_p;      /* ptr to next in chain       */
  311. #ifdef SNMP_DPI_VIEW_SELECTION
  312.   char                    view;        /* for BNR DPI version 1.2    */
  313. #endif
  314. #ifdef SNMP_DPI_BULK_SELECTION
  315.   char                    bulk;
  316. #endif
  317. #ifdef SNMP_DPI_REGISTER_WITH_COMMUNITY
  318.   unsigned short          community_len;  /* BNR DPI version 1.2     */
  319.   unsigned char          *community_p     /* compatibility           */
  320. #endif
  321. };
  322.  
  323. struct dpi_ureg_packet {
  324.   char                    reason_code; /* unregister reason code     */
  325.   char                   *group_p;     /* ptr to group OIDstring     */
  326.   struct dpi_ureg_packet *next_p;      /* ptr to next in chain       */
  327. };
  328.  
  329. struct dpi_get_packet {
  330.   char                   *object_p;    /* ptr to OIDstring (DPI 1.x) */
  331.   char                   *group_p;     /* ptr to group OIDstring     */
  332.   char                   *instance_p;  /* ptr to group OIDstring     */
  333.   struct dpi_get_packet  *next_p;      /* ptr to next in chain       */
  334. };
  335.  
  336. struct dpi_next_packet {
  337.   char                   *object_p;    /* ptr to OIDstring (DPI 1.x) */
  338.   char                   *group_p;     /* ptr to group OIDstring     */
  339.   char                   *instance_p;  /* ptr to group OIDstring     */
  340.   struct dpi_next_packet *next_p;      /* ptr to next in chain       */
  341. };
  342.  
  343. struct dpi_bulk_packet {
  344.   long int               non_repeaters;   /* number of non-repeaters */
  345.   long int               max_repetitions; /* max repeaters           */
  346.   struct dpi_next_packet *varBind_p;      /* ptr to varBinds: chain  */
  347.                                           /* of dpi_next_packets     */
  348. };
  349.  
  350. struct snmp_dpi_u64 {                  /* for unsigned 64-bit int    */
  351.   unsigned long high;                  /* - high order 32 bits       */
  352.   unsigned long low;                   /* - low order  32 bits       */
  353. };                                     /* for unsigned 64-bit int    */
  354. typedef struct snmp_dpi_u64 snmp_dpi_u64;
  355.  
  356. struct dpi_set_packet {
  357.   char                   *object_p;    /* ptr to OIDstring (DPI 1.x) */
  358.   char                   *group_p;     /* ptr to group OIDstring     */
  359.   char                   *instance_p;  /* ptr to group OIDstring     */
  360.   unsigned char           value_type;  /* value type; SNMP_TYPE_xxxx */
  361.   unsigned short          value_len;   /* value length               */
  362.   char                   *value_p;     /* ptr to the value itself    */
  363.   struct dpi_set_packet  *next_p;      /* ptr to next in chain       */
  364. };
  365.  
  366. struct dpi_resp_packet {
  367.   char                     error_code; /* error code: SNMP_ERROR_xxx */
  368.   unsigned long int        error_index;/* index 1st varBind in error */
  369.   #define  resp_priority   error_index /* for response to register   */
  370.   struct dpi_set_packet   *varBind_p;  /* ptr to varBinds: chain of  */
  371. };                                     /* dpi_set_packets            */
  372.  
  373. struct dpi_trap_packet {
  374.   long int                 generic;    /* long must be 4 bytes long  */
  375.   long int                 specific;
  376.   struct dpi_set_packet   *varBind_p;  /* ptr to varBinds: chain of  */
  377.                                        /* SET structures             */
  378.   char                    *enterprise_p; /* ptr to enterprise ID     */
  379. };
  380.  
  381. struct dpi_open_packet {
  382.   char                 *oid_p;         /* subagent ID, an OIDstring  */
  383.   char                 *description_p; /* subagent descriptive name  */
  384.   unsigned short        timeout;       /* in seconds, 16-bit u_int   */
  385.   unsigned short        max_varBinds;  /* max varBinds I can handle  */
  386.   char                  character_set; /* character set selection    */
  387.   unsigned short        password_len;  /* length of password         */
  388.   unsigned char        *password_p;    /* ptr to password itself     */
  389. };
  390.  
  391. struct dpi_close_packet {
  392.   char                  reason_code;   /* reason for closing         */
  393. };
  394.  
  395. typedef struct snmp_dpi_hdr             snmp_dpi_hdr;
  396. typedef struct dpi_open_packet          snmp_dpi_open_packet;
  397. typedef struct dpi_close_packet         snmp_dpi_close_packet;
  398. typedef struct dpi_reg_packet           snmp_dpi_reg_packet;
  399. typedef struct dpi_ureg_packet          snmp_dpi_ureg_packet;
  400. typedef struct dpi_get_packet           snmp_dpi_get_packet;
  401. typedef struct dpi_next_packet          snmp_dpi_next_packet;
  402. typedef struct dpi_bulk_packet          snmp_dpi_bulk_packet;
  403. typedef struct dpi_set_packet           snmp_dpi_set_packet;
  404. typedef struct dpi_resp_packet          snmp_dpi_resp_packet;
  405. typedef struct dpi_trap_packet          snmp_dpi_trap_packet;
  406.  
  407. #define snmp_dpi_hdr_NULL_p             ((snmp_dpi_hdr *)0)
  408. #define snmp_dpi_open_packet_NULL_p     ((snmp_dpi_open_packet *)0)
  409. #define snmp_dpi_close_packet_NULL_p    ((snmp_dpi_close_packet *)0)
  410. #define snmp_dpi_get_packet_NULL_p      ((snmp_dpi_get_packet *)0)
  411. #define snmp_dpi_next_packet_NULL_p     ((snmp_dpi_next_packet *)0)
  412. #define snmp_dpi_bulk_packet_NULL_p     ((snmp_dpi_bulk_packet *)0)
  413. #define snmp_dpi_set_packet_NULL_p      ((snmp_dpi_set_packet *)0)
  414. #define snmp_dpi_resp_packet_NULL_p     ((snmp_dpi_resp_packet *)0)
  415. #define snmp_dpi_trap_packet_NULL_p     ((snmp_dpi_trap_packet *)0)
  416. #define snmp_dpi_reg_packet_NULL_p      ((snmp_dpi_reg_packet *)0)
  417. #define snmp_dpi_ureg_packet_NULL_p     ((snmp_dpi_ureg_packet *)0)
  418.  
  419. struct snmp_dpi_hdr {
  420.   unsigned char  proto_major;
  421.   unsigned char  proto_version;
  422.   #define        proto_minor proto_version  /* for DPI 1.x */
  423.   unsigned char  proto_release;
  424.   unsigned short packet_id;                 /* 2 bytes; 16-bit int   */
  425.   unsigned char  packet_type;
  426.   union {
  427.      snmp_dpi_reg_packet      *reg_p;
  428.      snmp_dpi_ureg_packet     *ureg_p;
  429.      snmp_dpi_get_packet      *get_p;
  430.      snmp_dpi_next_packet     *next_p;
  431.      snmp_dpi_next_packet     *bulk_p;
  432.      snmp_dpi_set_packet      *set_p;
  433.      snmp_dpi_resp_packet     *resp_p;
  434.      snmp_dpi_trap_packet     *trap_p;
  435.      snmp_dpi_open_packet     *open_p;
  436.      snmp_dpi_close_packet    *close_p;
  437.      unsigned char            *any_p;
  438.   } data_u;
  439. #ifdef SNMP_DPI_VIEW_SELECTION
  440.   unsigned short community_len;             /* BNR DPI version 1.2   */
  441.   unsigned char *community_p;               /* compatibility fields  */
  442. #endif
  443. };
  444.  
  445. #if defined(__cplusplus)               /* C++ compiler               */
  446. #ifndef DPI_NO_EXTERN_C
  447. extern "C" {                           /* sees them as extern C      */
  448. #endif
  449. #endif /* __cplusplus */
  450.  
  451. /*********************************************************************/
  452. /* Following functions are common functions for DPI programmers:     */
  453. /* - DPIdebug can be used to turn all internal DPI tracing/debugging */
  454. /*   on or off. If turned on, the functions within the DPI library   */
  455. /*   report what happens via messages to stdout and/or stderr.       */
  456. /* - pDPIpacket can be used to create a parse tree from a DPI packet */
  457. /*   received on the "wire" or "connection".                         */
  458. /* - fDPIparse can be used to free the complete parse tree when it   */
  459. /*   is no longer needed. It will free all allocated memory.         */
  460. /* - fDPIset (defined as a macro above so that it translates into a  */
  461. /*   fDPIset_packet) can be used to free a complete SET parse tree   */
  462. /*   This was found to be needed/handy when preparing a SET tree for */
  463. /*   a reponse or trap and then running into an error so that the    */
  464. /*   tree is no longer needed, while there is no snmp_dpi_hdr (yet). */
  465. /*********************************************************************/
  466.  
  467. void   LINKAGE        DPIdebug(        /* Set all DPI internal debug */
  468.   int                   level);        /* zero=off; otherwise=on at  */
  469.                                        /* specified level            */
  470.  
  471. snmp_dpi_hdr * LINKAGE pDPIpacket(     /* parse a DPI packet         */
  472.   unsigned char        *packet_p);     /* ptr to the DPI packet      */
  473.  
  474. void     LINKAGE      fDPIparse(       /* free a DPI parse tree      */
  475.   snmp_dpi_hdr         *hdr_p);        /* ptr to parse tree          */
  476.  
  477. void     LINKAGE      fDPIset_packet(  /* free a DPI SET parse tree  */
  478.   snmp_dpi_set_packet  *packet_p);     /* ptr to SET packet (varBind)*/
  479.  
  480. /*********************************************************************/
  481. /* Following functions create a serialized SNMP DPI packet in a      */
  482. /* static buffer. There is only ONE such buffer, shared by all       */
  483. /* packet types. So access to the buffer must be serialized.         */
  484. /* - If success, a ptr to that buffer is returned.                   */
  485. /* - if failure, a NULL ptr is returned.                             */
  486. /*                                                                   */
  487. /* Note(s):                                                          */
  488. /* - If success, then the first 2 bytes (network byte order) of the  */
  489. /*   packet contain the length of remaining packet. Beware that the  */
  490. /*   complete packet (including the length bytes) must be sent over  */
  491. /*   to the other side of a DPI "connection". To calculate the total */
  492. /*   length, you can use the DPI_PACKET_LEN macro defined above.     */
  493. /* - The complete or partial parse tree that is passed to the PACKET,*/
  494. /*   RESP and TRAPe functions is ALWAYS freed by those functions.    */
  495. /*   So upon return from these funcions (successful or unsuccessful) */
  496. /*   one should not reference the parse tree anymore.                */
  497. /*********************************************************************/
  498. unsigned char * LINKAGE mkDPIpacket(   /* Make a DPI packet          */
  499.   snmp_dpi_hdr         *hdr_p);        /* ptr to a parse tree        */
  500.  
  501. unsigned char * LINKAGE mkDPIopen(     /* Make a DPI open packet     */
  502.   char                 *oid_p,         /* subagent Identifier (OID)  */
  503.   char                 *description_p, /* subagent descriptive name  */
  504.   unsigned long         timeout,       /* requested default timeout  */
  505.   unsigned long         max_varBinds,  /* max varBinds per DPI packet*/
  506.   char                  character_set, /* selected character set     */
  507.   #define DPI_NATIVE_CSET  0           /*   0 = native character set */
  508.   #define DPI_ASCII_CSET   1           /*   1 = ASCII  character set */
  509.   unsigned long         password_len,  /* length of pasword (if any) */
  510.   unsigned char        *password_p);   /* ptr to password (if any)   */
  511.  
  512. unsigned char * LINKAGE mkDPIclose(    /* Make a DPI close packet    */
  513.   char                  reason_code);  /* reason for closing         */
  514.  
  515. unsigned char * LINKAGE mkDPIreg(      /* Make a DPI register packet */
  516.   unsigned short        timeout,       /* in seconds (16-bit)        */
  517.   long int              priority,      /* requested priority         */
  518.   char                 *group_p,       /* ptr to group ID (subtree)  */
  519.   char                  bulk_select,   /* Bulk selection (GETBULK)   */
  520.   #define DPI_BULK_NO   0              /*  map GETBULK into GETNEXTs */
  521.   #define DPI_BULK_YES  1              /*  pass GETBULK to sub-agent */
  522.   char                  view_select);  /* View selection yes(1)/no(0)*/
  523.   #define DPI_VIEW_NO   0              /* (for BNR DPI version 1.2   */
  524.   #define DPI_VIEW_YES  1              /*  compatibility only)       */
  525.  
  526. unsigned char * LINKAGE mkDPIureg(     /* Make DPI unregister packet */
  527.   char                  reason_code,   /* subagent specific code     */
  528.   char                 *group_p);      /* ptr to group ID (subtree)  */
  529.  
  530. unsigned char * LINKAGE mkDPIbulk(     /* Make a DPI response packet */
  531.   long int             non_repeaters,  /* non repeaters              */
  532.   long int             max_repetitions,/* maximum repetitions        */
  533.   snmp_dpi_next_packet *packet_p);     /* ptr to chain of NEXT packts*/
  534.                                        /* containing the varBinds    */
  535.  
  536. unsigned char * LINKAGE mkDPIayt(void);/* Make DPI AreYouThere packet*/
  537.  
  538. unsigned char * LINKAGE mkDPIresp(     /* Make a DPI response packet */
  539.   snmp_dpi_hdr         *hdr_p,         /* ptr to packet to respond to*/
  540.   long int              ret_code,      /* error code: SNMP_ERROR_xxx */
  541.   long int              ret_index,     /* index to varBind in error  */
  542.   snmp_dpi_set_packet  *packet_p);     /* ptr to chain of SET packets*/
  543.                                        /* containing the varBinds    */
  544.  
  545. unsigned char * LINKAGE mkDPItrape(    /* Make a DPI trap packet     */
  546.   long int              generic,       /* generic trap type  (32 bit)*/
  547.   long int              specific,      /* specific trap type (32 bit)*/
  548.   snmp_dpi_set_packet  *packet_p,      /* ptr to chain of SET packets*/
  549.                                        /* containing the varBinds    */
  550.   char                 *enterprise_p); /* ptr to enterprise OID      */
  551.  
  552. /*********************************************************************/
  553. /* Following functions will create a complete or partial parse tree. */
  554. /* - If success, a ptr to the (complete or partial) parse tree is    */
  555. /*   returned.                                                       */
  556. /* - If failure, a NULL ptr is returned.                             */
  557. /*                                                                   */
  558. /* Note(s):                                                          */
  559. /* - All the callers other arguments are copied to newly and         */
  560. /*   and dynamically allocated memory, so callers ptrs are always    */
  561. /*   valid upon return (successful or unsuccessful).                 */
  562. /* - All required memory is dynamically allocated.                   */
  563. /* - The REG, UREG, GET, NEXT, SET, parse trees are formed by a      */
  564. /*   chain of packet structures. For these functions:                */
  565. /*   - When you pass a ptr to an existing chain of structures        */
  566. /*     (partial parse tree), then a new structure will be added at   */
  567. /*     the end of the chain.                                         */
  568. /*     Upon success, the returned ptr will be the ptr to the first   */
  569. /*     entry in the chain (e.g. the one you passed).                 */
  570. /*     Upon failure, you always get a NULL ptr returned, so you must */
  571. /*     ensure that you remember the ptr to the first entry.          */
  572. /*   - When you pass a NULL ptr to indicate that this is the first   */
  573. /*     structure you want to allocate, then a ptr to the new (and    */
  574. /*     thus first entry) structure will be returned (if success).    */
  575. /*   - All the callers other arguments are copied to newly and       */
  576. /*     and dynamically allocated memory, so callers ptrs are always  */
  577. /*     valid upon return (successful or unsuccessful).               */
  578. /* - The mkDPIhdrv() and mkDPInext_packet() are meant for use by an  */
  579. /*   agent and are most probably not needed by a subagent.           */
  580. /*********************************************************************/
  581. /* This macro for mkDPIhdr(a) provides the published mkDPIhdr()      */
  582. /* function that normally should be used by subagents:               */
  583. /*    snmp_dpi_hdr *mkDPIhdr(int dpi_packet_type)                    */
  584. /*********************************************************************/
  585. #define mkDPIhdr(a)   mkDPIhdr_version((a),SNMP_DPI_VERSION,         \
  586.                                            SNMP_DPI_RELEASE)
  587.  
  588. snmp_dpi_hdr * LINKAGE mkDPIhdr_version(/* Make DPIhdr for parse tree*/
  589.   int                   type,          /* packet type; SNMP_DPI_xxxx */
  590.   char                  version,       /* for this specific version  */
  591.   char                  release);      /* for this specific release  */
  592.  
  593. snmp_dpi_reg_packet * LINKAGE mkDPIreg_packet(/* Make DPIreg_packet  */
  594.   snmp_dpi_reg_packet  *packet_p,      /* ptr to REGISTER structure  */
  595.   unsigned short        timeout,       /* in seconds (16-bit)        */
  596.   long int              priority,      /* requested priority         */
  597.   char                 *group_p,       /* ptr to group ID (subtree)  */
  598.   char                  bulk_select,   /* Bulk selection yes(1)/no(0)*/
  599.   char                  view_select);  /* View selection yes(1)/no(0)*/
  600.                                        /* (for BNR DPI version 1.2   */
  601.                                        /*  compatibility only)       */
  602.  
  603. snmp_dpi_ureg_packet * LINKAGE mkDPIureg_packet(/* Make DPIureg packt*/
  604.   snmp_dpi_ureg_packet *packet_p,      /* ptr to UNREGISTER structure*/
  605.   char                  reason_code,   /* subagent specific code     */
  606.   char                 *group_p);      /* ptr to group ID (subtree)  */
  607.  
  608. snmp_dpi_get_packet  * LINKAGE mkDPIget_packet(/* Make DPIget packet */
  609.   snmp_dpi_get_packet  *packet_p,      /* ptr to GET structure       */
  610.   char                 *group_p,       /* ptr to group ID (subtree)  */
  611.   char                 *instance_p);   /* ptr to instance OID string */
  612.  
  613. snmp_dpi_next_packet * LINKAGE mkDPInext_packet(/* Make DPInext packt*/
  614.   snmp_dpi_next_packet *packet_p,      /* ptr to NEXT structure      */
  615.   char                 *group_p,       /* ptr to group ID (subtree)  */
  616.   char                 *instance_p);   /* ptr to instance OID string */
  617.  
  618. snmp_dpi_set_packet  * LINKAGE mkDPIset_packet(/* Make DPIset packet */
  619.   snmp_dpi_set_packet  *packet_p,      /* ptr to SET structure       */
  620.   char                 *group_p,       /* ptr to group ID (subtree)  */
  621.   char                 *instance_p,    /* ptr to instance OID string */
  622.   int                   value_type,    /* value type (SNMP_TYPE_xxx) */
  623.   int                   value_len,     /* length of value            */
  624.   void                 *value_p);      /* ptr to value               */
  625.  
  626. /*********************************************************************/
  627. /* The following functions are defined as part of the DPI interface  */
  628. /* for DPI subagents. They are system specific functions though, so  */
  629. /* they may or may not be available in the exact same form on all    */
  630. /* platforms or in all vendor provided DPI implementations. Check    */
  631. /* you platform/vendor documentation for exact specification.        */
  632. /*********************************************************************/
  633. /* Prototypes for SNMP-DPI communication (to/from agent) related     */
  634. /* functions. They invoke system dependent code that knows how to    */
  635. /* actually make/close the connections and how to send/receive data  */
  636. /* over these connections.                                           */
  637. /* - The connect functions:                                          */
  638. /*   - If success, return a positive handle that uniquely identifies */
  639. /*     the connection. To be passed when calling send/await function.*/
  640. /*   - If failure, return a negative error code (DPI_RC_xxxx)        */
  641. /* - The send/await/disconnect functions need the handle that        */
  642. /*   identifies the connection.                                      */
  643. /* - The send/await functions:                                       */
  644. /*   - If success, return a zero (DPI_RC_OK)                         */
  645. /*   - If failure, return a negative error code (DPI_RC_xxxx)        */
  646. /* - The qDPIport/lookup_host functions are for DPI 1.x compatibility*/
  647. /*   and for those who want to do communications themselves instead  */
  648. /*   of using DPIxxxx functions to connect/send/wait etc.            */
  649. /*********************************************************************/
  650. #define dpiPortForTCP               1  /* for use with qDPIport()    */
  651. #define dpiPortForUDP               2  /* porttype argument          */
  652. #define DPIconnect      DPIconnectTCP  /* default is TCP port        */
  653. #define DPI_RC_OK                   0  /* all OK, no error           */
  654. #define DPI_RC_NOK                 -1  /* some other error           */
  655. #define DPI_RC_NO_PORT             -2  /* cannot figure out DPI port */
  656. #define DPI_RC_NO_CONNECTION       -3  /* no connection to DPI agent */
  657. #define DPI_RC_EOF                 -4  /* EOF received on connection */
  658. #define DPI_RC_IO_ERROR            -5  /* Some I/O error on connect. */
  659. #define DPI_RC_INVALID_HANDLE      -6  /* unknown/invalid handle     */
  660. #define DPI_RC_TIMEOUT             -7  /* timeout occured            */
  661. #define DPI_RC_PACKET_TOO_LARGE    -8  /* packed too large, dropped  */
  662.  
  663. int LINKAGE  DPIconnect_to_agent_TCP(  /* Connect to DPI TCP port    */
  664.   char                 *hostname_p,    /* target hostname/IPaddress  */
  665.   char                 *community_p);  /* communityname              */
  666.  
  667. int LINKAGE  DPIconnect_to_agent_UDP(  /* Connect to DPI UDP port    */
  668.   char                 *hostname_p,    /* target hostname/IPaddress  */
  669.   char                 *community_p);  /* communityname              */
  670.  
  671. int LINKAGE  DPIconnect_to_agent_NMQ(  /* Connect to DPI Named Queue */
  672.   char                 *t_qname_p,     /* target (agent) queue name  */
  673.   char                 *s_qname_p);    /* source (subagent) q name   */
  674.  
  675. int LINKAGE  DPIconnect_to_agent_SHM(  /* Connect to DPI Shared Mem  */
  676.   int                   queue_id);     /* target (agent) queue id    */
  677.  
  678. int LINKAGE  DPIget_fd_for_handle(     /* get the filedescriptor for */
  679.   int                   handle);       /* this handle                */
  680.  
  681. void LINKAGE DPIdisconnect_from_agent( /* disconnect from DPI (agent)*/
  682.   int                   handle);       /* close this connection      */
  683.  
  684. int LINKAGE  DPIawait_packet_from_agent(  /* await a DPI packet      */
  685.   int                   handle,        /* on this connection         */
  686.   int                   timeout,       /* timeout in seconds.        */
  687.   unsigned char       **message_p,     /* receives ptr to data       */
  688.   unsigned long        *length);       /* receives length of data    */
  689.  
  690. int LINKAGE  DPIsend_packet_to_agent(  /* send a DPI packet          */
  691.   int                   handle,        /* on this connection         */
  692.   CONST unsigned char  *message_p,     /* the packet to send         */
  693.   unsigned long         length);       /* length of packet           */
  694.  
  695. long int  LINKAGE     qDPIport(        /* Query (GET) SNMP_DPI port  */
  696.   char                 *hostname_p,    /* target hostname/IPaddress  */
  697.   char                 *community_p,   /* communityname for GET      */
  698.   int                   porttype);     /* port instance, one of:     */
  699.                                        /*   dpiPortForTCP            */
  700.                                        /*   dpiPortForUDP            */
  701.  
  702. unsigned long  LINKAGE  lookup_host(   /* find IPaddress in network  */
  703.   char                 *hostname_p);   /* byte order for this host   */
  704.  
  705. #if defined(__cplusplus)               /* close up the C++  scope    */
  706. #ifndef DPI_NO_EXTERN_C
  707. }
  708. #endif
  709. #endif /* __cplusplus) */
  710.  
  711. #pragma pack()
  712.  
  713. #endif /* snmp_dpiH */
  714.  
  715. /*
  716. \end{verbatim}
  717. */
  718.