/[H8]/trunk/docs/Microchip TCP_IP stack/Include/TCPIP Stack/SNMP.h
ViewVC logotype

Annotation of /trunk/docs/Microchip TCP_IP stack/Include/TCPIP Stack/SNMP.h

Parent Directory Parent Directory | Revision Log Revision Log


Revision 15 - (hide annotations) (download)
Thu Apr 19 09:01:15 2007 UTC (17 years, 3 months ago) by hedin
File MIME type: text/plain
File size: 17298 byte(s)
added the TCP/IP stack, source code.
1 hedin 15 /*********************************************************************
2     *
3     * SNMP Defs for Microchip TCP/IP Stack
4     *
5     *********************************************************************
6     * FileName: SNMP.h
7     * Dependencies: StackTsk.h
8     * UDP.h
9     * Processor: PIC18
10     * Complier: MCC18 v1.00.50 or higher
11     * HITECH PICC-18 V8.10PL1 or higher
12     * Company: Microchip Technology, Inc.
13     *
14     * Software License Agreement
15     *
16     * Copyright © 2002-2007 Microchip Technology Inc. All rights
17     * reserved.
18     *
19     * Microchip licenses to you the right to use, modify, copy, and
20     * distribute:
21     * (i) the Software when embedded on a Microchip microcontroller or
22     * digital signal controller product (“Device”) which is
23     * integrated into Licensee’s product; or
24     * (ii) ONLY the Software driver source files ENC28J60.c and
25     * ENC28J60.h ported to a non-Microchip device used in
26     * conjunction with a Microchip ethernet controller for the
27     * sole purpose of interfacing with the ethernet controller.
28     *
29     * You should refer to the license agreement accompanying this
30     * Software for additional information regarding your rights and
31     * obligations.
32     *
33     * THE SOFTWARE AND DOCUMENTATION ARE PROVIDED “AS IS” WITHOUT
34     * WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING WITHOUT
35     * LIMITATION, ANY WARRANTY OF MERCHANTABILITY, FITNESS FOR A
36     * PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT SHALL
37     * MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR
38     * CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, COST OF
39     * PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS
40     * BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE
41     * THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER
42     * SIMILAR COSTS, WHETHER ASSERTED ON THE BASIS OF CONTRACT, TORT
43     * (INCLUDING NEGLIGENCE), BREACH OF WARRANTY, OR OTHERWISE.
44     *
45     * Author Date Comment
46     *~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
47     * Nilesh Rajbharti 1/9/03 Original (Rev 1.0)
48     ********************************************************************/
49     #ifndef SNMP_H
50     #define SNMP_H
51    
52    
53     /*
54     * This is the file that contains SNMP BIB file.
55     * File name must contain all upper case letter and must match
56     * with what was included in MPFS image.
57     */
58     #define SNMP_BIB_FILE_NAME "SNMP.BIB"
59    
60    
61     /*
62     * This is the maximum length for community string.
63     * Application must ensure that this length is observed.
64     * SNMP module does not check for length overflow.
65     */
66     #define SNMP_COMMUNITY_MAX_LEN (8)
67     #define NOTIFY_COMMUNITY_LEN (SNMP_COMMUNITY_MAX_LEN)
68    
69     /*
70     * Change this to match your OID string length.
71     */
72     #define OID_MAX_LEN (15)
73    
74    
75    
76     #define SNMP_START_OF_VAR (0)
77     #define SNMP_END_OF_VAR (0xff)
78     #define SNMP_INDEX_INVALID (0xff)
79    
80     /*********************************************************************
81     * Function: void SNMPInit(void)
82     *
83     * PreCondition: At least one UDP socket must be available.
84     * UDPInit() is already called.
85     *
86     * Input: None
87     *
88     * Output: SNMP agent module is initialized.
89     *
90     * Side Effects: One UDP socket will be used.
91     *
92     * Overview: Initialize SNMP module internals
93     *
94     * Note: This function is called only once during lifetime
95     * of the application.
96     ********************************************************************/
97     void SNMPInit(void);
98    
99     /*********************************************************************
100     * Function: BOOL SNMPTask(void)
101     *
102     * PreCondition: SNMPInit is already called.
103     *
104     * Input: None
105     *
106     * Output: TRUE if SNMP module has finished with a state
107     * FALSE if a state has not been finished.
108     *
109     *
110     * Side Effects: None
111     *
112     * Overview: Handle incoming SNMP requests as well as any
113     * outgoing SNMP responses and timeout conditions
114     *
115     * Note: None.
116     ********************************************************************/
117     BOOL SNMPTask(void);
118    
119    
120     /*
121     * This is the SNMP OID variable id.
122     * This id is assigned via MIB file. Only dynamic and AgentID
123     * variables can contian ID. MIB2BIB utility enforces this
124     * rules when BIB was generated.
125     */
126     typedef BYTE SNMP_ID;
127     typedef BYTE SNMP_INDEX;
128    
129     typedef union _SNMP_VAL
130     {
131     DWORD dword;
132     WORD word;
133     BYTE byte;
134     BYTE v[sizeof(DWORD)];
135     } SNMP_VAL;
136    
137     /*********************************************************************
138     * Function: BOOL SNMPGetVar(SNMP_ID var, SNMP_INDEX index,
139     * BYTE *ref, SNMP_VAL* val)
140     *
141     * PreCondition: None
142     *
143     * Input: var - Variable id whose value is to be returned
144     * index - Index of variable that should be
145     * transferred
146     * ref - Variable reference used to transfer
147     * multi-byte data
148     * It is always SNMP_START_OF_VAR when very
149     * first byte is requested.
150     * Otherwise, use this as a reference to
151     * keep track of multi-byte transfers.
152     * val - Pointer to up to 4 byte buffer.
153     * If var data type is BYTE, transfer data
154     * in val->byte
155     * If var data type is WORD, transfer data in
156     * val->word
157     * If var data type is DWORD, transfer data in
158     * val->dword
159     * If var data type is IP_ADDRESS, transfer data
160     * in val->v[] or val->dword
161     * If var data type is COUNTER32, TIME_TICKS or
162     * GAUGE32, transfer data in val->dword
163     * If var data type is ASCII_STRING or OCTET_STRING
164     * transfer data in val->byte using multi-byte
165     * transfer mechanism.
166     *
167     * Output: TRUE if a value exists for given variable at given
168     * index.
169     * FALSE otherwise.
170     *
171     * Side Effects: None
172     *
173     * Overview: This is a callback function called by SNMP module.
174     * SNMP user must implement this function in
175     * user application and provide appropriate data when
176     * called.
177     *
178     * Note: None
179     ********************************************************************/
180     #ifdef __SNMP_C
181     extern BOOL SNMPGetVar(SNMP_ID var, SNMP_INDEX index,
182     BYTE *ref, SNMP_VAL* val);
183     #endif
184    
185    
186     /*********************************************************************
187     * Function: BOOL SNMPGetNextIndex(SNMP_ID var,
188     * SNMP_INDEX *index)
189     *
190     * PreCondition: None
191     *
192     * Input: var - Variable id whose value is to be returned
193     * idnex - Next Index of variable that should be
194     * transferred
195     *
196     * Output: TRUE if a next index value exists for given variable at given
197     * index and index parameter contains next valid index.
198     * FALSE otherwise.
199     *
200     * Side Effects: None
201     *
202     * Overview: This is a callback function called by SNMP module.
203     * SNMP user must implement this function in
204     * user application and provide appropriate data when
205     * called. This function will only be called for
206     * OID variable of type sequence.
207     *
208     * Note: None
209     ********************************************************************/
210     #ifdef __SNMP_C
211     extern BOOL SNMPGetNextIndex(SNMP_ID var, SNMP_INDEX *index);
212     #endif
213    
214    
215     /*********************************************************************
216     * Function: BOOL SNMPIsValidSetLen(SNMP_ID var, BYTE len)
217     *
218     * PreCondition: None
219     *
220     * Input: var - Variable id whose value is to be set
221     * len - Length value that is to be validated.
222     *
223     * Output: TRUE if given var can be set to given len
224     * FALSE if otherwise.
225     *
226     * Side Effects: None
227     *
228     * Overview: This is a callback function called by module.
229     * User application must implement this function.
230     *
231     * Note: This function will be called for only variables
232     * that are defined as ASCII_STRING and OCTET_STRING
233     * (i.e. data length greater than 4 bytes)
234     ********************************************************************/
235     #ifdef __SNMP_C
236     extern BOOL SNMPIsValidSetLen(SNMP_ID var, BYTE len);
237     #endif
238    
239    
240     /*********************************************************************
241     * Function: BOOL SNMPSetVar(SNMP_ID var, SNMP_INDEX index,
242     * BYTE ref, SNMP_VAL val)
243     *
244     * PreCondition: None
245     *
246     * Input: var - Variable id whose value is to be set
247     * ref - Variable reference used to transfer
248     * multi-byte data
249     * 0 if first byte is set
250     * otherwise nonzero value to indicate
251     * corresponding byte being set.
252     * val - Up to 4 byte data value.
253     * If var data type is BYTE, variable
254     * value is in val->byte
255     * If var data type is WORD, variable
256     * value is in val->word
257     * If var data type is DWORD, variable
258     * value is in val->dword.
259     * If var data type is IP_ADDRESS, COUNTER32,
260     * or GAUGE32, value is in val->dword
261     * If var data type is OCTET_STRING, ASCII_STRING
262     * value is in val->byte; multi-byte transfer
263     * will be performed to transfer remaining
264     * bytes of data.
265     *
266     * Output: TRUE if it is OK to set more byte(s).
267     * FALSE if otherwise.
268     *
269     * Side Effects: None
270     *
271     * Overview: This is a callback function called by module.
272     * User application must implement this function.
273     *
274     * Note: This function may get called more than once
275     * depending on number of bytes in a specific
276     * set request for given variable.
277     ********************************************************************/
278     #ifdef __SNMP_C
279     extern BOOL SNMPSetVar(SNMP_ID var, SNMP_INDEX index,
280     BYTE ref, SNMP_VAL val);
281     #endif
282    
283    
284    
285     /*
286     * This is the list of SNMP action a remote NMS can perform.
287     * This inforamtion is passed to application via
288     * callback SNMPValidate.
289     * Application should validate the action for given community
290     * string.
291     */
292     typedef enum _SNMP_ACTION
293     {
294     SNMP_GET = 0xa0,
295     SNMP_GET_NEXT = 0xa1,
296     SNMP_GET_RESPONSE = 0xa2,
297     SNMP_SET = 0xa3,
298     SNMP_TRAP = 0xa4,
299     SNMP_ACTION_UNKNOWN = 0
300     } SNMP_ACTION;
301    
302     /*********************************************************************
303     * Function: BOOL SNMPValidate(SNMP_ACTION SNMPAction,
304     * char* community)
305     *
306     * PreCondition: SNMPInit is already called.
307     *
308     * Input: SNMPAction - SNMP_GET to fetch a variable
309     * SNMP_SET to write to a variable
310     * community - Community string as sent by NMS
311     *
312     * Output: TRUE if password matches with given community
313     * FALSE if otherwise.
314     *
315     * Side Effects: None
316     *
317     * Overview: This is a callback function called by module.
318     * User application must implement this function
319     * and verify that community matches with predefined
320     * value.
321     *
322     * Note: This validation occurs for each NMS request.
323     ********************************************************************/
324     #ifdef __SNMP_C
325     extern BOOL SNMPValidate(SNMP_ACTION SNMPAction, char* community);
326     #endif
327    
328    
329    
330     /*********************************************************************
331     * Function: void SNMPNotifyPrepare(IP_ADDR *remoteHost,
332     * char *community,
333     * BYTE communityLen,
334     * SNMP_ID agentIDVar,
335     * BYTE notificationCode,
336     * DWORD timestamp)
337     *
338     * PreCondition: SNMPInit is already called.
339     *
340     * Input: remoteHost - pointer to remote Host IP address
341     * community - Community string to use to notify
342     * communityLen- Community string length
343     * agentIDVar - System ID to use identify this agent
344     * notificaitonCode - Notification Code to use
345     * timestamp - Notification timestamp in 100th
346     * of second.
347     *
348     * Output: None
349     *
350     * Side Effects: None
351     *
352     * Overview: This function prepares SNMP module to send SNMP
353     * trap (notification) to remote host.
354     *
355     * Note: This is first of series of functions to complete
356     * SNMP notification.
357     ********************************************************************/
358     void SNMPNotifyPrepare(IP_ADDR *remoteHost,
359     char *community,
360     BYTE communityLen,
361     SNMP_ID agentIDVar,
362     BYTE notificationCode,
363     DWORD timestamp);
364    
365    
366     /*********************************************************************
367     * Function: BOOL SNMPIsNotifyReady(IP_ADDR *remoteHost)
368     *
369     * PreCondition: SNMPNotifyPrepare is already called and returned
370     * TRUE.
371     *
372     * Input: remoteHost - pointer to remote Host IP address
373     *
374     * Output: TRUE if remoteHost IP address is resolved and
375     * SNMPNotify may be called.
376     * FALSE otherwise.
377     * This would fail if there were not UDP socket
378     * to open.
379     *
380     * Side Effects: None
381     *
382     * Overview: This function resolves given remoteHost IP address
383     * into MAC address using ARP module.
384     * If remoteHost is not aviailable, this function
385     * would never return TRUE.
386     * Application must implement timeout logic to
387     * handle "remoteHost not avialable" situation.
388     *
389     * Note: None
390     ********************************************************************/
391     BOOL SNMPIsNotifyReady(IP_ADDR *remoteHost);
392    
393    
394     /*********************************************************************
395     * Function: BOOL SNMPNotify(SNMP_ID var,
396     * SNMP_VAL val,
397     * SNMP_INDEX index)
398     *
399     * PreCondition: SNMPIsNotified is already called and returned
400     * TRUE.
401     *
402     * Input: var - SNMP var ID that is to be used in
403     * notification
404     * val - Value of var. Only value of
405     * BYTE, WORD or DWORD can be sent.
406     * index - Index of var. If this var is a single,
407     * index would be 0, or else if this var
408     * is a sequence, index could be any
409     * value from 0 to 127.
410     *
411     * Output: TRUE if SNMP notification was successful sent.
412     * This does not guarantee that remoteHost recieved
413     * it.
414     * FALSE otherwise.
415     * This would fail under following contions:
416     * 1) Given SNMP_BIB_FILE does not exist in MPFS
417     * 2) Given var does not exist.
418     * 3) Previously given agentID does not exist
419     * 4) Data type of given var is unknown - only
420     * possible if MPFS itself was corrupted.
421     *
422     * Side Effects: None
423     *
424     * Overview: This function creates SNMP trap PDU and sends it
425     * to previously specified remoteHost.
426     *
427     * Note: None
428     ********************************************************************/
429     BOOL SNMPNotify(SNMP_ID var, SNMP_VAL val, SNMP_INDEX index);
430    
431    
432    
433    
434    
435     #endif

  ViewVC Help
Powered by ViewVC 1.1.20