blob: 11ca3a08786d8ef022b1a267943a80372706114a [file] [log] [blame]
Dave Shield4530d872011-06-24 12:08:23 +00001.TH "Net-SNMP Agent handler and extensibility API" 3 "24 Jun 2011" "Version 5.4.3.pre1" "net-snmp" \" -*- nroff -*-
Wes Hardaker27ff28a2002-04-20 00:29:28 +00002.ad l
3.nh
4.SH NAME
Dave Shield8080a812011-05-06 17:22:14 +00005Net-SNMP Agent handler and extensibility API \-
Robert Story2254d872004-09-02 05:57:42 +00006.PP
Dave Shieldcac11a92011-06-01 15:08:51 +00007The basic theory goes something like this: In the past, with the original mib \fBmodule\fP api (which derived from the original CMU SNMP code) the underlying mib modules were passed very little information (only the truly most basic information about a request).
Wes Hardaker27ff28a2002-04-20 00:29:28 +00008
Robert Story2254d872004-09-02 05:57:42 +00009.SS "Data Structures"
10
11.in +1c
12.ti -1c
13.RI "struct \fBnetsnmp_mib_handler_s\fP"
14.br
15.RI "\fIthe mib handler structure to be registered \fP"
16.ti -1c
17.RI "struct \fBnetsnmp_handler_registration_s\fP"
18.br
19.RI "\fIRoot registration info. \fP"
20.ti -1c
21.RI "struct \fBnetsnmp_handler_args_s\fP"
22.br
23.ti -1c
24.RI "struct \fBnetsnmp_delegated_cache_s\fP"
25.br
Dave Shield3f6f5332009-10-29 10:30:23 +000026.in -1c
27.SS "Modules"
28
29.in +1c
Robert Story2254d872004-09-02 05:57:42 +000030.ti -1c
Dave Shield3f6f5332009-10-29 10:30:23 +000031.RI "\fButility_handlers\fP"
Robert Story2254d872004-09-02 05:57:42 +000032.br
Dave Shield3f6f5332009-10-29 10:30:23 +000033.PP
34
35.RI "\fISimplify request processing A group of handlers intended to simplify certain aspects of processing a request for a MIB object. \fP"
Robert Story2254d872004-09-02 05:57:42 +000036.ti -1c
Dave Shield3f6f5332009-10-29 10:30:23 +000037.RI "\fBleaf_handlers\fP"
Robert Story2254d872004-09-02 05:57:42 +000038.br
Dave Shield3f6f5332009-10-29 10:30:23 +000039.PP
40
41.RI "\fIProcess individual leaf objects A group of handlers to implement individual leaf objects and instances (both scalar objects, and individual objects and instances within a table). \fP"
42.ti -1c
43.RI "\fBbaby_steps\fP"
44.br
45.PP
46
47.RI "\fICalls your handler in baby_steps for set processing. \fP"
48.ti -1c
49.RI "\fBold_api\fP"
50.br
51.PP
52
Dave Shieldcac11a92011-06-01 15:08:51 +000053.RI "\fICalls mib \fBmodule\fP code written in the old style of code. \fP"
Dave Shield3f6f5332009-10-29 10:30:23 +000054.ti -1c
55.RI "\fBstash_cache\fP"
56.br
57.PP
58
59.RI "\fIAutomatically caches data for certain handlers. \fP"
60.ti -1c
61.RI "\fBtable\fP"
62.br
63.PP
64
65.RI "\fIHelps you implement a table. \fP"
Robert Story2254d872004-09-02 05:57:42 +000066.in -1c
67.SS "Defines"
68
69.in +1c
70.ti -1c
71.RI "#define \fBMIB_HANDLER_AUTO_NEXT\fP 0x00000001"
72.br
73.ti -1c
74.RI "#define \fBMIB_HANDLER_AUTO_NEXT_OVERRIDE_ONCE\fP 0x00000002"
75.br
76.ti -1c
Wes Hardakerfdd56482006-09-20 00:29:56 +000077.RI "#define \fBMIB_HANDLER_INSTANCE\fP 0x00000004"
78.br
79.ti -1c
Robert Story2254d872004-09-02 05:57:42 +000080.RI "#define \fBMIB_HANDLER_CUSTOM4\fP 0x10000000"
81.br
82.ti -1c
83.RI "#define \fBMIB_HANDLER_CUSTOM3\fP 0x20000000"
84.br
85.ti -1c
86.RI "#define \fBMIB_HANDLER_CUSTOM2\fP 0x40000000"
87.br
88.ti -1c
89.RI "#define \fBMIB_HANDLER_CUSTOM1\fP 0x80000000"
90.br
91.ti -1c
Wes Hardakerfdd56482006-09-20 00:29:56 +000092.RI "#define \fBHANDLER_CAN_GETANDGETNEXT\fP 0x01"
Robert Story2254d872004-09-02 05:57:42 +000093.br
94.ti -1c
Wes Hardakerfdd56482006-09-20 00:29:56 +000095.RI "#define \fBHANDLER_CAN_SET\fP 0x02"
Robert Story2254d872004-09-02 05:57:42 +000096.br
97.ti -1c
98.RI "#define \fBHANDLER_CAN_GETBULK\fP 0x04"
99.br
100.ti -1c
Wes Hardakerfdd56482006-09-20 00:29:56 +0000101.RI "#define \fBHANDLER_CAN_NOT_CREATE\fP 0x08"
Robert Story2254d872004-09-02 05:57:42 +0000102.br
103.ti -1c
104.RI "#define \fBHANDLER_CAN_BABY_STEP\fP 0x10"
105.br
106.ti -1c
Robert Story6fbe1942005-10-31 09:27:14 +0000107.RI "#define \fBHANDLER_CAN_STASH\fP 0x20"
108.br
109.ti -1c
Robert Story2254d872004-09-02 05:57:42 +0000110.RI "#define \fBHANDLER_CAN_RONLY\fP (HANDLER_CAN_GETANDGETNEXT)"
111.br
112.ti -1c
113.RI "#define \fBHANDLER_CAN_RWRITE\fP (HANDLER_CAN_GETANDGETNEXT | HANDLER_CAN_SET)"
114.br
115.ti -1c
116.RI "#define \fBHANDLER_CAN_SET_ONLY\fP (HANDLER_CAN_SET | HANDLER_CAN_NOT_CREATE)"
117.br
118.ti -1c
119.RI "#define \fBHANDLER_CAN_DEFAULT\fP (HANDLER_CAN_RONLY | HANDLER_CAN_NOT_CREATE)"
120.br
121.ti -1c
122.RI "#define \fBREQUEST_IS_DELEGATED\fP 1"
123.br
124.ti -1c
125.RI "#define \fBREQUEST_IS_NOT_DELEGATED\fP 0"
126.br
127.in -1c
128.SS "Typedefs"
129
130.in +1c
131.ti -1c
Dave Shield3f6f5332009-10-29 10:30:23 +0000132.RI "typedef struct \fBnetsnmp_mib_handler_s\fP \fBnetsnmp_mib_handler\fP"
Robert Story2254d872004-09-02 05:57:42 +0000133.br
134.RI "\fITypedefs the \fBnetsnmp_mib_handler_s\fP struct into netsnmp_mib_handler. \fP"
135.ti -1c
Dave Shield3f6f5332009-10-29 10:30:23 +0000136.RI "typedef struct \fBnetsnmp_handler_registration_s\fP \fBnetsnmp_handler_registration\fP"
Robert Story2254d872004-09-02 05:57:42 +0000137.br
138.RI "\fITypedefs the \fBnetsnmp_handler_registration_s\fP struct into netsnmp_handler_registration. \fP"
139.ti -1c
Wes Hardakera7e42af2007-05-21 23:51:45 +0000140.RI "typedef int( \fBNetsnmp_Node_Handler\fP )(\fBnetsnmp_mib_handler\fP *handler, \fBnetsnmp_handler_registration\fP *reginfo, \fBnetsnmp_agent_request_info\fP *reqinfo, \fBnetsnmp_request_info\fP *requests)"
Robert Story2254d872004-09-02 05:57:42 +0000141.br
142.ti -1c
Dave Shield3f6f5332009-10-29 10:30:23 +0000143.RI "typedef struct \fBnetsnmp_handler_args_s\fP \fBnetsnmp_handler_args\fP"
Robert Story2254d872004-09-02 05:57:42 +0000144.br
145.ti -1c
Dave Shield3f6f5332009-10-29 10:30:23 +0000146.RI "typedef struct \fBnetsnmp_delegated_cache_s\fP \fBnetsnmp_delegated_cache\fP"
Robert Story2254d872004-09-02 05:57:42 +0000147.br
148.in -1c
Wes Hardaker27ff28a2002-04-20 00:29:28 +0000149.SS "Functions"
150
151.in +1c
152.ti -1c
Dave Shield3f6f5332009-10-29 10:30:23 +0000153.RI "\fBnetsnmp_mib_handler\fP * \fBnetsnmp_create_handler\fP (const char *name, Netsnmp_Node_Handler *handler_access_method)"
Wes Hardaker27ff28a2002-04-20 00:29:28 +0000154.br
Robert Story2254d872004-09-02 05:57:42 +0000155.RI "\fIcreates a netsnmp_mib_handler structure given a name and a access method. \fP"
Wes Hardaker27ff28a2002-04-20 00:29:28 +0000156.ti -1c
Robert Story2254d872004-09-02 05:57:42 +0000157.RI "\fBnetsnmp_handler_registration\fP * \fBnetsnmp_handler_registration_create\fP (const char *name, \fBnetsnmp_mib_handler\fP *handler, oid *reg_oid, size_t reg_oid_len, int modes)"
Wes Hardaker27ff28a2002-04-20 00:29:28 +0000158.br
Robert Story2254d872004-09-02 05:57:42 +0000159.RI "\fIcreates a handler registration structure given a name, a access_method function, a registration location oid and the modes the handler supports. \fP"
Wes Hardaker27ff28a2002-04-20 00:29:28 +0000160.ti -1c
Dave Shield3f6f5332009-10-29 10:30:23 +0000161.RI "\fBnetsnmp_handler_registration\fP * \fBnetsnmp_create_handler_registration\fP (const char *name, Netsnmp_Node_Handler *handler_access_method, oid *reg_oid, size_t reg_oid_len, int modes)"
Wes Hardaker27ff28a2002-04-20 00:29:28 +0000162.br
Wes Hardaker27ff28a2002-04-20 00:29:28 +0000163.ti -1c
Robert Story2254d872004-09-02 05:57:42 +0000164.RI "int \fBnetsnmp_register_handler\fP (\fBnetsnmp_handler_registration\fP *reginfo)"
Wes Hardaker27ff28a2002-04-20 00:29:28 +0000165.br
Robert Story2254d872004-09-02 05:57:42 +0000166.RI "\fIregister a handler, as defined by the netsnmp_handler_registration pointer. \fP"
Wes Hardaker27ff28a2002-04-20 00:29:28 +0000167.ti -1c
Robert Story2254d872004-09-02 05:57:42 +0000168.RI "int \fBnetsnmp_unregister_handler\fP (\fBnetsnmp_handler_registration\fP *reginfo)"
Wes Hardaker27ff28a2002-04-20 00:29:28 +0000169.br
Robert Story2254d872004-09-02 05:57:42 +0000170.RI "\fIunregister a handler, as defined by the netsnmp_handler_registration pointer. \fP"
Wes Hardaker27ff28a2002-04-20 00:29:28 +0000171.ti -1c
Robert Story2254d872004-09-02 05:57:42 +0000172.RI "int \fBnetsnmp_register_handler_nocallback\fP (\fBnetsnmp_handler_registration\fP *reginfo)"
Wes Hardaker27ff28a2002-04-20 00:29:28 +0000173.br
Robert Story2254d872004-09-02 05:57:42 +0000174.RI "\fIregister a handler, as defined by the netsnmp_handler_registration pointer. \fP"
Wes Hardaker27ff28a2002-04-20 00:29:28 +0000175.ti -1c
Robert Story2254d872004-09-02 05:57:42 +0000176.RI "int \fBnetsnmp_inject_handler_before\fP (\fBnetsnmp_handler_registration\fP *reginfo, \fBnetsnmp_mib_handler\fP *handler, const char *before_what)"
Wes Hardaker27ff28a2002-04-20 00:29:28 +0000177.br
Bart Van Assche2cec6242011-07-26 14:59:33 +0200178.RI "\fIinject a new handler into the calling chain of the handlers defined by the netsnmp_handler_registration pointer. \fP"
Wes Hardaker27ff28a2002-04-20 00:29:28 +0000179.ti -1c
Robert Story2254d872004-09-02 05:57:42 +0000180.RI "int \fBnetsnmp_inject_handler\fP (\fBnetsnmp_handler_registration\fP *reginfo, \fBnetsnmp_mib_handler\fP *handler)"
Wes Hardaker27ff28a2002-04-20 00:29:28 +0000181.br
Bart Van Assche2cec6242011-07-26 14:59:33 +0200182.RI "\fIinject a new handler into the calling chain of the handlers defined by the netsnmp_handler_registration pointer. \fP"
Wes Hardaker27ff28a2002-04-20 00:29:28 +0000183.ti -1c
Robert Story2254d872004-09-02 05:57:42 +0000184.RI "NETSNMP_INLINE int \fBnetsnmp_call_handler\fP (\fBnetsnmp_mib_handler\fP *next_handler, \fBnetsnmp_handler_registration\fP *reginfo, \fBnetsnmp_agent_request_info\fP *reqinfo, \fBnetsnmp_request_info\fP *requests)"
Wes Hardaker2ce26ca2002-08-02 21:31:02 +0000185.br
Robert Story2254d872004-09-02 05:57:42 +0000186.RI "\fIcalls a handler with with appropriate NULL checking of arguments, etc. \fP"
Wes Hardaker2ce26ca2002-08-02 21:31:02 +0000187.ti -1c
Robert Story2254d872004-09-02 05:57:42 +0000188.RI "int \fBnetsnmp_call_handlers\fP (\fBnetsnmp_handler_registration\fP *reginfo, \fBnetsnmp_agent_request_info\fP *reqinfo, \fBnetsnmp_request_info\fP *requests)"
Wes Hardaker27ff28a2002-04-20 00:29:28 +0000189.br
Wes Hardaker27ff28a2002-04-20 00:29:28 +0000190.ti -1c
Robert Story2254d872004-09-02 05:57:42 +0000191.RI "NETSNMP_INLINE int \fBnetsnmp_call_next_handler\fP (\fBnetsnmp_mib_handler\fP *current, \fBnetsnmp_handler_registration\fP *reginfo, \fBnetsnmp_agent_request_info\fP *reqinfo, \fBnetsnmp_request_info\fP *requests)"
Wes Hardaker27ff28a2002-04-20 00:29:28 +0000192.br
Robert Story2254d872004-09-02 05:57:42 +0000193.RI "\fIcalls the next handler in the chain after the current one with with appropriate NULL checking, etc. \fP"
Wes Hardaker27ff28a2002-04-20 00:29:28 +0000194.ti -1c
Robert Story2254d872004-09-02 05:57:42 +0000195.RI "NETSNMP_INLINE int \fBnetsnmp_call_next_handler_one_request\fP (\fBnetsnmp_mib_handler\fP *current, \fBnetsnmp_handler_registration\fP *reginfo, \fBnetsnmp_agent_request_info\fP *reqinfo, \fBnetsnmp_request_info\fP *requests)"
Wes Hardaker27ff28a2002-04-20 00:29:28 +0000196.br
Robert Story2254d872004-09-02 05:57:42 +0000197.RI "\fIcalls the next handler in the chain after the current one with with appropriate NULL checking, etc. \fP"
Wes Hardaker27ff28a2002-04-20 00:29:28 +0000198.ti -1c
Robert Story2254d872004-09-02 05:57:42 +0000199.RI "void \fBnetsnmp_handler_free\fP (\fBnetsnmp_mib_handler\fP *handler)"
Wes Hardaker27ff28a2002-04-20 00:29:28 +0000200.br
Dave Shield8080a812011-05-06 17:22:14 +0000201.RI "\fIfrees the resources associated with a given handler \fP"
Wes Hardaker27ff28a2002-04-20 00:29:28 +0000202.ti -1c
Robert Story2254d872004-09-02 05:57:42 +0000203.RI "\fBnetsnmp_mib_handler\fP * \fBnetsnmp_handler_dup\fP (\fBnetsnmp_mib_handler\fP *handler)"
Wes Hardaker27ff28a2002-04-20 00:29:28 +0000204.br
Bart Van Asschef650bca2010-10-15 10:02:35 +0000205.RI "\fIduplicates a handler and all subsequent handlers see also _clone_handler \fP"
Robert Story2254d872004-09-02 05:57:42 +0000206.ti -1c
207.RI "void \fBnetsnmp_handler_registration_free\fP (\fBnetsnmp_handler_registration\fP *reginfo)"
208.br
209.RI "\fIfree the resources associated with a handler registration object \fP"
210.ti -1c
211.RI "\fBnetsnmp_handler_registration\fP * \fBnetsnmp_handler_registration_dup\fP (\fBnetsnmp_handler_registration\fP *reginfo)"
212.br
213.RI "\fIduplicates the handler registration object \fP"
214.ti -1c
Wes Hardakerfdd56482006-09-20 00:29:56 +0000215.RI "NETSNMP_INLINE \fBnetsnmp_delegated_cache\fP * \fBnetsnmp_create_delegated_cache\fP (\fBnetsnmp_mib_handler\fP *handler, \fBnetsnmp_handler_registration\fP *reginfo, \fBnetsnmp_agent_request_info\fP *reqinfo, \fBnetsnmp_request_info\fP *requests, void *localinfo)"
Robert Story2254d872004-09-02 05:57:42 +0000216.br
217.RI "\fIcreates a cache of information which can be saved for future reference. \fP"
Wes Hardaker27ff28a2002-04-20 00:29:28 +0000218.ti -1c
Wes Hardakerfdd56482006-09-20 00:29:56 +0000219.RI "NETSNMP_INLINE \fBnetsnmp_delegated_cache\fP * \fBnetsnmp_handler_check_cache\fP (\fBnetsnmp_delegated_cache\fP *dcache)"
Wes Hardaker27ff28a2002-04-20 00:29:28 +0000220.br
Robert Story2254d872004-09-02 05:57:42 +0000221.RI "\fIcheck's a given cache and returns it if it is still valid (ie, the agent still considers it to be an outstanding request. \fP"
Wes Hardaker27ff28a2002-04-20 00:29:28 +0000222.ti -1c
Wes Hardakerfdd56482006-09-20 00:29:56 +0000223.RI "NETSNMP_INLINE void \fBnetsnmp_free_delegated_cache\fP (\fBnetsnmp_delegated_cache\fP *dcache)"
Wes Hardaker27ff28a2002-04-20 00:29:28 +0000224.br
Robert Story2254d872004-09-02 05:57:42 +0000225.RI "\fIfrees a cache once you're finished using it \fP"
Wes Hardaker27ff28a2002-04-20 00:29:28 +0000226.ti -1c
Robert Story2254d872004-09-02 05:57:42 +0000227.RI "void \fBnetsnmp_handler_mark_requests_as_delegated\fP (\fBnetsnmp_request_info\fP *requests, int isdelegated)"
Wes Hardaker27ff28a2002-04-20 00:29:28 +0000228.br
Robert Story2254d872004-09-02 05:57:42 +0000229.RI "\fImarks a list of requests as delegated (or not if isdelegaded = 0) \fP"
Wes Hardaker27ff28a2002-04-20 00:29:28 +0000230.ti -1c
Wes Hardakerfdd56482006-09-20 00:29:56 +0000231.RI "NETSNMP_INLINE void \fBnetsnmp_request_add_list_data\fP (\fBnetsnmp_request_info\fP *request, \fBnetsnmp_data_list\fP *\fBnode\fP)"
Wes Hardaker27ff28a2002-04-20 00:29:28 +0000232.br
Robert Story2254d872004-09-02 05:57:42 +0000233.RI "\fIadd data to a request that can be extracted later by submodules \fP"
Wes Hardaker27ff28a2002-04-20 00:29:28 +0000234.ti -1c
Robert Story2254d872004-09-02 05:57:42 +0000235.RI "NETSNMP_INLINE int \fBnetsnmp_request_remove_list_data\fP (\fBnetsnmp_request_info\fP *request, const char *name)"
Wes Hardaker27ff28a2002-04-20 00:29:28 +0000236.br
Robert Story2254d872004-09-02 05:57:42 +0000237.RI "\fIremove data from a request \fP"
Wes Hardaker27ff28a2002-04-20 00:29:28 +0000238.ti -1c
Dave Shield633890c2010-03-14 22:10:19 +0000239.RI "void * \fBnetsnmp_request_get_list_data\fP (\fBnetsnmp_request_info\fP *request, const char *name)"
Wes Hardaker27ff28a2002-04-20 00:29:28 +0000240.br
Dave Shieldcac11a92011-06-01 15:08:51 +0000241.RI "\fIextract data from a request that was added previously by a parent \fBmodule\fP \fP"
Wes Hardaker27ff28a2002-04-20 00:29:28 +0000242.ti -1c
Robert Story2254d872004-09-02 05:57:42 +0000243.RI "NETSNMP_INLINE void \fBnetsnmp_free_request_data_set\fP (\fBnetsnmp_request_info\fP *request)"
Wes Hardaker27ff28a2002-04-20 00:29:28 +0000244.br
Robert Story2254d872004-09-02 05:57:42 +0000245.RI "\fIFree the extra data stored in a request. \fP"
Wes Hardaker27ff28a2002-04-20 00:29:28 +0000246.ti -1c
Robert Story2254d872004-09-02 05:57:42 +0000247.RI "NETSNMP_INLINE void \fBnetsnmp_free_request_data_sets\fP (\fBnetsnmp_request_info\fP *request)"
Wes Hardaker27ff28a2002-04-20 00:29:28 +0000248.br
Dave Shieldcac11a92011-06-01 15:08:51 +0000249.RI "\fIFree the extra data stored in a bunch of requests (all data in the chain). \fP"
Wes Hardaker27ff28a2002-04-20 00:29:28 +0000250.ti -1c
Robert Story2254d872004-09-02 05:57:42 +0000251.RI "\fBnetsnmp_mib_handler\fP * \fBnetsnmp_find_handler_by_name\fP (\fBnetsnmp_handler_registration\fP *reginfo, const char *name)"
Wes Hardaker27ff28a2002-04-20 00:29:28 +0000252.br
Robert Story2254d872004-09-02 05:57:42 +0000253.RI "\fIReturns a handler from a chain based on the name. \fP"
Wes Hardaker27ff28a2002-04-20 00:29:28 +0000254.ti -1c
Robert Story2254d872004-09-02 05:57:42 +0000255.RI "void * \fBnetsnmp_find_handler_data_by_name\fP (\fBnetsnmp_handler_registration\fP *reginfo, const char *name)"
Wes Hardaker27ff28a2002-04-20 00:29:28 +0000256.br
Robert Story2254d872004-09-02 05:57:42 +0000257.RI "\fIReturns a handler's void * pointer from a chain based on the name. \fP"
Wes Hardaker27ff28a2002-04-20 00:29:28 +0000258.ti -1c
Dave Shield8080a812011-05-06 17:22:14 +0000259.RI "void \fBhandler_free_callback\fP (void *handler)"
Wes Hardaker27ff28a2002-04-20 00:29:28 +0000260.br
Robert Story2254d872004-09-02 05:57:42 +0000261.ti -1c
262.RI "void \fBnetsnmp_register_handler_by_name\fP (const char *name, \fBnetsnmp_mib_handler\fP *handler)"
263.br
264.RI "\fIregisters a given handler by name so that it can be found easily later. \fP"
Wes Hardaker27ff28a2002-04-20 00:29:28 +0000265.ti -1c
Wes Hardakera8bd6492003-09-06 05:06:03 +0000266.RI "void \fBnetsnmp_clear_handler_list\fP (void)"
Wes Hardaker27ff28a2002-04-20 00:29:28 +0000267.br
Robert Story2254d872004-09-02 05:57:42 +0000268.RI "\fIclears the entire handler-registration list \fP"
269.ti -1c
Wes Hardakerfdd56482006-09-20 00:29:56 +0000270.RI "void \fBnetsnmp_inject_handler_into_subtree\fP (\fBnetsnmp_subtree\fP *tp, const char *name, \fBnetsnmp_mib_handler\fP *handler, const char *before_what)"
Robert Story2254d872004-09-02 05:57:42 +0000271.br
272.ti -1c
273.RI "void \fBparse_injectHandler_conf\fP (const char *token, char *cptr)"
274.br
275.ti -1c
276.RI "void \fBnetsnmp_init_handler_conf\fP (void)"
277.br
278.ti -1c
279.RI "void * \fBnetsnmp_handler_get_parent_data\fP (\fBnetsnmp_request_info\fP *, const char *)"
280.br
Wes Hardaker27ff28a2002-04-20 00:29:28 +0000281.in -1c
Robert Story2254d872004-09-02 05:57:42 +0000282.SH "Detailed Description"
Wes Hardaker27ff28a2002-04-20 00:29:28 +0000283.PP
Dave Shieldcac11a92011-06-01 15:08:51 +0000284The basic theory goes something like this: In the past, with the original mib \fBmodule\fP api (which derived from the original CMU SNMP code) the underlying mib modules were passed very little information (only the truly most basic information about a request).
Dave Shield3f6f5332009-10-29 10:30:23 +0000285
Wes Hardakerfdd56482006-09-20 00:29:56 +0000286This worked well at the time but in todays world of subagents, device instrumentation, low resource consumption, etc, it just isn't flexible enough. 'handlers' are here to fix all that.
Wes Hardaker27ff28a2002-04-20 00:29:28 +0000287.PP
288With the rewrite of the agent internals for the net-snmp 5.0 release, we introduce a modular calling scheme that allows agent modules to be written in a very flexible manner, and more importantly allows reuse of code in a decent way (and without the memory and speed overheads of OO languages like C++).
289.PP
Dave Shieldcac11a92011-06-01 15:08:51 +0000290Functionally, the notion of what a handler does is the same as the older api: A handler is \fBcreated\fP and then \fBregistered\fP with the main agent at a given OID in the OID \fBtree\fP and gets called any time a request is made that it should respond to. You probably should use one of the convenience helpers instead of doing anything else yourself though:
Wes Hardaker27ff28a2002-04-20 00:29:28 +0000291.PP
Dave Shieldcac11a92011-06-01 15:08:51 +0000292Most importantly, though, is that the handlers are built on the notion of modularity and reuse. Specifically, rather than do all the really hard work (like parsing table indexes out of an incoming oid request) in each \fBmodule\fP, the API is designed to make it easy to write 'helper' handlers that merely process some aspect of the request before passing it along to the final handler that returns the real answer. Most people will want to make use of the \fBinstance\fP, \fBtable\fP, \fBtable_iterator\fP, \fBtable_data\fP, or \fBtable_dataset\fP helpers to make their life easier. These 'helpers' interpert important aspects of the request and pass them on to you.
Wes Hardaker27ff28a2002-04-20 00:29:28 +0000293.PP
Wes Hardakerfdd56482006-09-20 00:29:56 +0000294For instance, the \fBtable\fP helper is designed to hand you a list of extracted index values from an incoming request. THe \fBtable_iterator\fP helper is built on top of the table helper, and is designed to help you iterate through data stored elsewhere (like in a kernel) that is not in OID lexographical order (ie, don't write your own index/oid sorting routine, use this helper instead). The beauty of the \fBtable_iterator helper\fP, as well as the \fBinstance\fP helper is that they take care of the complex GETNEXT processing entirely for you and hand you everything you need to merely return the data as if it was a GET request. Much less code and hair pulling. I've pulled all my hair out to help you so that only one of us has to be bald.
Robert Story2254d872004-09-02 05:57:42 +0000295.SH "Typedef Documentation"
Wes Hardaker27ff28a2002-04-20 00:29:28 +0000296.PP
Robert Story2254d872004-09-02 05:57:42 +0000297.SS "struct \fBnetsnmp_handler_registration_s\fP \fBnetsnmp_handler_registration\fP"
Wes Hardaker27ff28a2002-04-20 00:29:28 +0000298.PP
Wes Hardakerfdd56482006-09-20 00:29:56 +0000299Typedefs the \fBnetsnmp_handler_registration_s\fP struct into netsnmp_handler_registration.
Robert Story2254d872004-09-02 05:57:42 +0000300.SS "struct \fBnetsnmp_mib_handler_s\fP \fBnetsnmp_mib_handler\fP"
Wes Hardaker27ff28a2002-04-20 00:29:28 +0000301.PP
Wes Hardakerfdd56482006-09-20 00:29:56 +0000302Typedefs the \fBnetsnmp_mib_handler_s\fP struct into netsnmp_mib_handler.
Robert Story2254d872004-09-02 05:57:42 +0000303.SH "Function Documentation"
304.PP
Dave Shieldcac11a92011-06-01 15:08:51 +0000305.SS "int netsnmp_call_handler (\fBnetsnmp_mib_handler\fP * next_handler, \fBnetsnmp_handler_registration\fP * reginfo, \fBnetsnmp_agent_request_info\fP * reqinfo, \fBnetsnmp_request_info\fP * requests)"
Wes Hardakercb5885f2003-11-14 02:42:44 +0000306.PP
Wes Hardakerfdd56482006-09-20 00:29:56 +0000307calls a handler with with appropriate NULL checking of arguments, etc.
Dave Shieldcac11a92011-06-01 15:08:51 +0000308.SS "int netsnmp_call_next_handler (\fBnetsnmp_mib_handler\fP * current, \fBnetsnmp_handler_registration\fP * reginfo, \fBnetsnmp_agent_request_info\fP * reqinfo, \fBnetsnmp_request_info\fP * requests)"
Wes Hardaker27ff28a2002-04-20 00:29:28 +0000309.PP
Wes Hardakerfdd56482006-09-20 00:29:56 +0000310calls the next handler in the chain after the current one with with appropriate NULL checking, etc.
Dave Shieldcac11a92011-06-01 15:08:51 +0000311.SS "int netsnmp_call_next_handler_one_request (\fBnetsnmp_mib_handler\fP * current, \fBnetsnmp_handler_registration\fP * reginfo, \fBnetsnmp_agent_request_info\fP * reqinfo, \fBnetsnmp_request_info\fP * requests)"
Wes Hardakercb5885f2003-11-14 02:42:44 +0000312.PP
Wes Hardakerfdd56482006-09-20 00:29:56 +0000313calls the next handler in the chain after the current one with with appropriate NULL checking, etc.
Wes Hardakera8bd6492003-09-06 05:06:03 +0000314.SS "void netsnmp_clear_handler_list (void)"
315.PP
Wes Hardakerfdd56482006-09-20 00:29:56 +0000316clears the entire handler-registration list
Dave Shieldcac11a92011-06-01 15:08:51 +0000317.SS "\fBnetsnmp_delegated_cache\fP * netsnmp_create_delegated_cache (\fBnetsnmp_mib_handler\fP * handler, \fBnetsnmp_handler_registration\fP * reginfo, \fBnetsnmp_agent_request_info\fP * reqinfo, \fBnetsnmp_request_info\fP * requests, void * localinfo)"
Wes Hardakerfdd56482006-09-20 00:29:56 +0000318.PP
Dave Shield3f6f5332009-10-29 10:30:23 +0000319creates a cache of information which can be saved for future reference. Use \fBnetsnmp_handler_check_cache()\fP later to make sure it's still valid before referencing it in the future.
Wes Hardaker27ff28a2002-04-20 00:29:28 +0000320.PP
321\fBExamples: \fP
322.in +1c
323\fBdelayed_instance.c\fP.
Dave Shieldcac11a92011-06-01 15:08:51 +0000324.SS "\fBnetsnmp_mib_handler\fP * netsnmp_create_handler (const char * name, Netsnmp_Node_Handler * handler_access_method)"
Wes Hardaker27ff28a2002-04-20 00:29:28 +0000325.PP
Dave Shield3f6f5332009-10-29 10:30:23 +0000326creates a netsnmp_mib_handler structure given a name and a access method. The returned handler should then be \fBregistered.\fP
Wes Hardaker27ff28a2002-04-20 00:29:28 +0000327.PP
Robert Story2254d872004-09-02 05:57:42 +0000328\fBParameters:\fP
329.RS 4
330\fIname\fP is the handler name and is copied then assigned to netsnmp_mib_handler->handler_name
331.br
332\fIhandler_access_method\fP is a function pointer used as the access method for this handler registration instance for whatever required needs.
333.RE
Wes Hardaker27ff28a2002-04-20 00:29:28 +0000334.PP
Robert Story2254d872004-09-02 05:57:42 +0000335\fBReturns:\fP
336.RS 4
337a pointer to a populated netsnmp_mib_handler struct to be registered
338.RE
Wes Hardaker27ff28a2002-04-20 00:29:28 +0000339.PP
Robert Story2254d872004-09-02 05:57:42 +0000340\fBSee also:\fP
341.RS 4
Dave Shield3f6f5332009-10-29 10:30:23 +0000342netsnmp_create_handler_registration()
Wes Hardakercb5885f2003-11-14 02:42:44 +0000343.PP
Robert Story2254d872004-09-02 05:57:42 +0000344\fBnetsnmp_register_handler()\fP
345.RE
Wes Hardakercb5885f2003-11-14 02:42:44 +0000346.PP
Wes Hardakerfdd56482006-09-20 00:29:56 +0000347
Dave Shieldcac11a92011-06-01 15:08:51 +0000348.SS "\fBnetsnmp_mib_handler\fP * netsnmp_find_handler_by_name (\fBnetsnmp_handler_registration\fP * reginfo, const char * name)"
Wes Hardaker27ff28a2002-04-20 00:29:28 +0000349.PP
Wes Hardakerfdd56482006-09-20 00:29:56 +0000350Returns a handler from a chain based on the name.
Dave Shieldcac11a92011-06-01 15:08:51 +0000351.SS "void * netsnmp_find_handler_data_by_name (\fBnetsnmp_handler_registration\fP * reginfo, const char * name)"
Wes Hardaker27ff28a2002-04-20 00:29:28 +0000352.PP
Dave Shield3f6f5332009-10-29 10:30:23 +0000353Returns a handler's void * pointer from a chain based on the name. This probably shouldn't be used by the general public as the void * data may change as a handler evolves. Handlers should really advertise some function for you to use instead.
Dave Shieldcac11a92011-06-01 15:08:51 +0000354.SS "void netsnmp_free_delegated_cache (\fBnetsnmp_delegated_cache\fP * dcache)"
Wes Hardaker27ff28a2002-04-20 00:29:28 +0000355.PP
Robert Story2254d872004-09-02 05:57:42 +0000356frees a cache once you're finished using it
Wes Hardaker27ff28a2002-04-20 00:29:28 +0000357.PP
358\fBExamples: \fP
359.in +1c
360\fBdelayed_instance.c\fP.
Dave Shieldcac11a92011-06-01 15:08:51 +0000361.SS "void netsnmp_free_request_data_set (\fBnetsnmp_request_info\fP * request)"
Wes Hardaker27ff28a2002-04-20 00:29:28 +0000362.PP
Wes Hardakerfdd56482006-09-20 00:29:56 +0000363Free the extra data stored in a request.
Dave Shieldcac11a92011-06-01 15:08:51 +0000364.SS "void netsnmp_free_request_data_sets (\fBnetsnmp_request_info\fP * request)"
Wes Hardakercb5885f2003-11-14 02:42:44 +0000365.PP
Dave Shieldcac11a92011-06-01 15:08:51 +0000366Free the extra data stored in a bunch of requests (all data in the chain).
367.SS "\fBnetsnmp_delegated_cache\fP * netsnmp_handler_check_cache (\fBnetsnmp_delegated_cache\fP * dcache)"
Wes Hardakerfdd56482006-09-20 00:29:56 +0000368.PP
Dave Shield3f6f5332009-10-29 10:30:23 +0000369check's a given cache and returns it if it is still valid (ie, the agent still considers it to be an outstanding request. Returns NULL if it's no longer valid.
Wes Hardaker27ff28a2002-04-20 00:29:28 +0000370.PP
371\fBExamples: \fP
372.in +1c
373\fBdelayed_instance.c\fP.
Dave Shieldcac11a92011-06-01 15:08:51 +0000374.SS "\fBnetsnmp_mib_handler\fP * netsnmp_handler_dup (\fBnetsnmp_mib_handler\fP * handler)"
Wes Hardaker27ff28a2002-04-20 00:29:28 +0000375.PP
Bart Van Asschef650bca2010-10-15 10:02:35 +0000376duplicates a handler and all subsequent handlers see also _clone_handler
Dave Shieldcac11a92011-06-01 15:08:51 +0000377.SS "void netsnmp_handler_free (\fBnetsnmp_mib_handler\fP * handler)"
Wes Hardaker27ff28a2002-04-20 00:29:28 +0000378.PP
Dave Shield8080a812011-05-06 17:22:14 +0000379frees the resources associated with a given handler
Wes Hardakercb5885f2003-11-14 02:42:44 +0000380.PP
Dave Shield8080a812011-05-06 17:22:14 +0000381make sure we aren't pointing to ourselves.
Dave Shieldcac11a92011-06-01 15:08:51 +0000382.SS "void netsnmp_handler_mark_requests_as_delegated (\fBnetsnmp_request_info\fP * requests, int isdelegated)"
Wes Hardaker27ff28a2002-04-20 00:29:28 +0000383.PP
Wes Hardakerfdd56482006-09-20 00:29:56 +0000384marks a list of requests as delegated (or not if isdelegaded = 0)
Dave Shieldcac11a92011-06-01 15:08:51 +0000385.SS "\fBnetsnmp_handler_registration\fP * netsnmp_handler_registration_create (const char * name, \fBnetsnmp_mib_handler\fP * handler, oid * reg_oid, size_t reg_oid_len, int modes)"
Wes Hardaker27ff28a2002-04-20 00:29:28 +0000386.PP
Dave Shield3f6f5332009-10-29 10:30:23 +0000387creates a handler registration structure given a name, a access_method function, a registration location oid and the modes the handler supports. If modes == 0, then modes will automatically be set to the default value of only HANDLER_CAN_DEFAULT, which is by default read-only GET and GETNEXT requests. A hander which supports sets but not row creation should set us a mode of HANDLER_CAN_SET_ONLY.
Wes Hardaker27ff28a2002-04-20 00:29:28 +0000388.PP
Robert Story2254d872004-09-02 05:57:42 +0000389\fBNote:\fP
390.RS 4
391This ends up calling netsnmp_create_handler(name, handler_access_method)
392.RE
Wes Hardakercb5885f2003-11-14 02:42:44 +0000393.PP
Robert Story2254d872004-09-02 05:57:42 +0000394\fBParameters:\fP
395.RS 4
396\fIname\fP is the handler name and is copied then assigned to netsnmp_handler_registration->handlerName.
397.br
Wes Hardakerfdd56482006-09-20 00:29:56 +0000398\fIhandler\fP is a function pointer used as the access method for this handler registration instance for whatever required needs.
Robert Story2254d872004-09-02 05:57:42 +0000399.br
400\fIreg_oid\fP is the registration location oid.
401.br
402\fIreg_oid_len\fP is the length of reg_oid, can use the macro, OID_LENGTH
403.br
404\fImodes\fP is used to configure read/write access. If modes == 0, then modes will automatically be set to the default value of only HANDLER_CAN_DEFAULT, which is by default read-only GET and GETNEXT requests. The other two mode options are read only, HANDLER_CAN_RONLY, and read/write, HANDLER_CAN_RWRITE.
405.RE
Wes Hardaker27ff28a2002-04-20 00:29:28 +0000406.PP
Robert Story2254d872004-09-02 05:57:42 +0000407.IP "\(bu" 2
408HANDLER_CAN_GETANDGETNEXT
409.IP "\(bu" 2
410HANDLER_CAN_SET
411.IP "\(bu" 2
412HANDLER_CAN_GETBULK
Wes Hardaker27ff28a2002-04-20 00:29:28 +0000413.PP
Wes Hardakercb5885f2003-11-14 02:42:44 +0000414.PP
Robert Story2254d872004-09-02 05:57:42 +0000415.IP "\(bu" 2
416HANDLER_CAN_RONLY (HANDLER_CAN_GETANDGETNEXT)
417.IP "\(bu" 2
418HANDLER_CAN_RWRITE (HANDLER_CAN_GETANDGETNEXT | HANDLER_CAN_SET)
419.IP "\(bu" 2
420HANDLER_CAN_DEFAULT HANDLER_CAN_RONLY
Wes Hardakercb5885f2003-11-14 02:42:44 +0000421.PP
Wes Hardaker27ff28a2002-04-20 00:29:28 +0000422.PP
Robert Story2254d872004-09-02 05:57:42 +0000423\fBReturns:\fP
424.RS 4
425Returns a pointer to a netsnmp_handler_registration struct. NULL is returned only when memory could not be allocated for the netsnmp_handler_registration struct.
426.RE
Wes Hardaker27ff28a2002-04-20 00:29:28 +0000427.PP
Robert Story2254d872004-09-02 05:57:42 +0000428\fBSee also:\fP
429.RS 4
430\fBnetsnmp_create_handler()\fP
Wes Hardaker27ff28a2002-04-20 00:29:28 +0000431.PP
Robert Story2254d872004-09-02 05:57:42 +0000432\fBnetsnmp_register_handler()\fP
433.RE
Wes Hardakercb5885f2003-11-14 02:42:44 +0000434.PP
Wes Hardakerfdd56482006-09-20 00:29:56 +0000435
Dave Shieldcac11a92011-06-01 15:08:51 +0000436.SS "\fBnetsnmp_handler_registration\fP * netsnmp_handler_registration_dup (\fBnetsnmp_handler_registration\fP * reginfo)"
Wes Hardakera8bd6492003-09-06 05:06:03 +0000437.PP
Wes Hardakerfdd56482006-09-20 00:29:56 +0000438duplicates the handler registration object
Dave Shieldcac11a92011-06-01 15:08:51 +0000439.SS "void netsnmp_handler_registration_free (\fBnetsnmp_handler_registration\fP * reginfo)"
Wes Hardakera8bd6492003-09-06 05:06:03 +0000440.PP
Wes Hardakerfdd56482006-09-20 00:29:56 +0000441free the resources associated with a handler registration object
Dave Shieldcac11a92011-06-01 15:08:51 +0000442.SS "int netsnmp_inject_handler (\fBnetsnmp_handler_registration\fP * reginfo, \fBnetsnmp_mib_handler\fP * handler)"
Robert Story2254d872004-09-02 05:57:42 +0000443.PP
Bart Van Assche2cec6242011-07-26 14:59:33 +0200444inject a new handler into the calling chain of the handlers defined by the netsnmp_handler_registration pointer. The new handler is injected at the top of the list and hence will be the new handler to be called first.
Dave Shieldcac11a92011-06-01 15:08:51 +0000445.SS "int netsnmp_inject_handler_before (\fBnetsnmp_handler_registration\fP * reginfo, \fBnetsnmp_mib_handler\fP * handler, const char * before_what)"
Robert Story2254d872004-09-02 05:57:42 +0000446.PP
Bart Van Assche2cec6242011-07-26 14:59:33 +0200447inject a new handler into the calling chain of the handlers defined by the netsnmp_handler_registration pointer. The new handler is injected after the before_what handler, or if NULL at the top of the list and hence will be the new handler to be called first.
Dave Shieldcac11a92011-06-01 15:08:51 +0000448.SS "int netsnmp_register_handler (\fBnetsnmp_handler_registration\fP * reginfo)"
Wes Hardaker27ff28a2002-04-20 00:29:28 +0000449.PP
Wes Hardakerfdd56482006-09-20 00:29:56 +0000450register a handler, as defined by the netsnmp_handler_registration pointer.
Dave Shieldcac11a92011-06-01 15:08:51 +0000451.SS "void netsnmp_register_handler_by_name (const char * name, \fBnetsnmp_mib_handler\fP * handler)"
Wes Hardakercb5885f2003-11-14 02:42:44 +0000452.PP
Wes Hardakerfdd56482006-09-20 00:29:56 +0000453registers a given handler by name so that it can be found easily later.
Dave Shieldcac11a92011-06-01 15:08:51 +0000454.SS "int netsnmp_register_handler_nocallback (\fBnetsnmp_handler_registration\fP * reginfo)"
Wes Hardakercb5885f2003-11-14 02:42:44 +0000455.PP
Wes Hardakerfdd56482006-09-20 00:29:56 +0000456register a handler, as defined by the netsnmp_handler_registration pointer.
Dave Shieldcac11a92011-06-01 15:08:51 +0000457.SS "void netsnmp_request_add_list_data (\fBnetsnmp_request_info\fP * request, \fBnetsnmp_data_list\fP * node)"
Wes Hardaker27ff28a2002-04-20 00:29:28 +0000458.PP
Dave Shield3f6f5332009-10-29 10:30:23 +0000459add data to a request that can be extracted later by submodules \fBParameters:\fP
Robert Story2254d872004-09-02 05:57:42 +0000460.RS 4
Wes Hardakerfdd56482006-09-20 00:29:56 +0000461\fIrequest\fP the netsnmp request info structure
Robert Story2254d872004-09-02 05:57:42 +0000462.br
Dave Shieldcac11a92011-06-01 15:08:51 +0000463\fI\fBnode\fP\fP this is the data to be added to the linked list request->parent_data
Robert Story2254d872004-09-02 05:57:42 +0000464.RE
465.PP
466\fBReturns:\fP
467.RS 4
468void
469.RE
470.PP
471
Wes Hardaker27ff28a2002-04-20 00:29:28 +0000472.PP
473\fBExamples: \fP
474.in +1c
475\fBdelayed_instance.c\fP.
Dave Shieldcac11a92011-06-01 15:08:51 +0000476.SS "void * netsnmp_request_get_list_data (\fBnetsnmp_request_info\fP * request, const char * name)"
Wes Hardaker27ff28a2002-04-20 00:29:28 +0000477.PP
Dave Shieldcac11a92011-06-01 15:08:51 +0000478extract data from a request that was added previously by a parent \fBmodule\fP \fBParameters:\fP
Robert Story2254d872004-09-02 05:57:42 +0000479.RS 4
480\fIrequest\fP the netsnmp request info function
481.br
482\fIname\fP used to compare against the request->parent_data->name value, if a match is found request->parent_data->data is returned
483.RE
484.PP
485\fBReturns:\fP
486.RS 4
487a void pointer(request->parent_data->data), otherwise NULL is returned if request is NULL or request->parent_data is NULL or request->parent_data object is not found.
488.RE
489.PP
490
Wes Hardaker27ff28a2002-04-20 00:29:28 +0000491.PP
492\fBExamples: \fP
493.in +1c
494\fBdelayed_instance.c\fP.
Dave Shieldcac11a92011-06-01 15:08:51 +0000495.SS "int netsnmp_request_remove_list_data (\fBnetsnmp_request_info\fP * request, const char * name)"
Robert Story2254d872004-09-02 05:57:42 +0000496.PP
Dave Shield3f6f5332009-10-29 10:30:23 +0000497remove data from a request \fBParameters:\fP
Robert Story2254d872004-09-02 05:57:42 +0000498.RS 4
Wes Hardakerfdd56482006-09-20 00:29:56 +0000499\fIrequest\fP the netsnmp request info structure
Robert Story2254d872004-09-02 05:57:42 +0000500.br
501\fIname\fP this is the name of the previously added data
502.RE
503.PP
504\fBReturns:\fP
505.RS 4
5060 on successful find-and-delete, 1 otherwise.
507.RE
508.PP
Wes Hardakerfdd56482006-09-20 00:29:56 +0000509
Dave Shieldcac11a92011-06-01 15:08:51 +0000510.SS "int netsnmp_unregister_handler (\fBnetsnmp_handler_registration\fP * reginfo)"
Robert Story2254d872004-09-02 05:57:42 +0000511.PP
Wes Hardakerfdd56482006-09-20 00:29:56 +0000512unregister a handler, as defined by the netsnmp_handler_registration pointer.
Dave Shield3f6f5332009-10-29 10:30:23 +0000513.SH "Author"
514.PP
515Generated automatically by Doxygen for net-snmp from the source code.