001: /*_############################################################################
002: _##
003: _## SNMP4J - MessageProcessingModel.java
004: _##
005: _## Copyright (C) 2003-2008 Frank Fock and Jochen Katz (SNMP4J.org)
006: _##
007: _## Licensed under the Apache License, Version 2.0 (the "License");
008: _## you may not use this file except in compliance with the License.
009: _## You may obtain a copy of the License at
010: _##
011: _## http://www.apache.org/licenses/LICENSE-2.0
012: _##
013: _## Unless required by applicable law or agreed to in writing, software
014: _## distributed under the License is distributed on an "AS IS" BASIS,
015: _## WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
016: _## See the License for the specific language governing permissions and
017: _## limitations under the License.
018: _##
019: _##########################################################################*/
020:
021: package org.snmp4j.mp;
022:
023: import java.io.IOException;
024: import org.snmp4j.*;
025: import org.snmp4j.smi.*;
026: import org.snmp4j.asn1.BERInputStream;
027: import org.snmp4j.MutablePDU;
028: import org.snmp4j.MessageDispatcher;
029: import org.snmp4j.asn1.BEROutputStream; // needed by JavaDoc:
030: import org.snmp4j.security.SecurityLevel;
031: import org.snmp4j.security.SecurityModel;
032:
033: /**
034: * The <code>MessageProcessingModel</code> interface defines common methods
035: * to all SNMP message processing models.
036: * <p>Note: The read counter of the {@link BERInputStream} parameters in this
037: * interface should not be reset while those methods are executed.
038: *
039: * @author Frank Fock
040: * @version 1.0
041: */
042: public interface MessageProcessingModel {
043:
044: int MPv1 = 0;
045: int MPv2c = 1;
046: int MPv2u = 2;
047: int MPv3 = 3;
048:
049: /**
050: * Gets the numerical ID of the message processing model as defined by the
051: * constants in this interface or by an appropriate constant in the
052: * class implementing this interface.
053: * @return
054: * a positive integer value.
055: */
056: int getID();
057:
058: /**
059: * Prepares an outgoing message as defined in RFC3412 §7.1.
060: *
061: * @param transportAddress
062: * the destination transport <code>Address</code>.
063: * @param maxMsgSize
064: * the maximum message size the transport mapping for the destination
065: * address is capable of.
066: * @param messageProcessingModel
067: * the {@link MessageProcessingModel} ID (typically, the SNMP version).
068: * @param securityModel
069: * the security model ID (see {@link SecurityModel}) to use.
070: * @param securityName
071: * the principal on behalf the message is to be sent.
072: * @param securityLevel
073: * the level of security requested (see {@link SecurityLevel}).
074: * @param pdu
075: * the <code>PDU</code> to send. For a SNMPv1 trap <code>pdu</code> has
076: * to be a {@link PDUv1} instance, for SNMPv3 messages it has to be a
077: * {@link ScopedPDU} instance.
078: * @param expectResponse
079: * indicates if a message expects a response. This has to be
080: * <code>true</code> for confirmed class PDUs and <code>false</code>
081: * otherwise.
082: * @param sendPduHandle
083: * the <code>PduHandle</code> that uniquely identifies the sent message.
084: * @param destTransportAddress
085: * returns the destination transport address (currently set always set to
086: * <code>transportAddress</code>.
087: * @param outgoingMessage
088: * returns the message to send.
089: * @throws IOException if the supplied PDU could not be encoded to the
090: * <code>outgoingMessage</code>
091: * @return
092: * the status of the message preparation. {@link SnmpConstants#SNMP_MP_OK}
093: * is returned if on success, otherwise any of the
094: * <code>SnmpConstants.SNMP_MP_*</code> values may be returned.
095: */
096: int prepareOutgoingMessage(Address transportAddress,
097: int maxMsgSize, int messageProcessingModel,
098: int securityModel, byte[] securityName, int securityLevel,
099: /* the following parameters are given in ScopedPDU
100: byte[] contextEngineID,
101: byte[] contextName,
102: */
103: PDU pdu, boolean expectResponse, PduHandle sendPduHandle,
104: Address destTransportAddress,
105: BEROutputStream outgoingMessage) throws IOException;
106:
107: /**
108: * Prepares a response message as defined in RFC3412 §7.1.
109: *
110: * @param messageProcessingModel int
111: * the {@link MessageProcessingModel} ID (typically, the SNMP version).
112: * @param maxMsgSize
113: * the maximum message size the transport mapping for the destination
114: * address is capable of.
115: * @param securityModel
116: * the security model ID (see {@link SecurityModel}) to use.
117: * @param securityName
118: * the principal on behalf the message is to be sent.
119: * @param securityLevel
120: * the level of security requested (see {@link SecurityLevel}).
121: * @param pdu
122: * the <code>PDU</code> to send. For a SNMPv1 trap <code>pdu</code> has
123: * to be a {@link PDUv1} instance, for SNMPv3 messages it has to be a
124: * {@link ScopedPDU} instance.
125: * @param maxSizeResponseScopedPDU
126: * the maximum size of the scoped PDU the sender (of the request) can
127: * accept.
128: * @param stateReference
129: * reference to state information presented with the request.
130: * @param statusInformation
131: * returns success or error indication. When an error occured, the error
132: * counter OID and value are included.
133: * @param outgoingMessage
134: * returns the message to send.
135: * @throws IOException
136: * if an internal error or a resource exception occured.
137: * @return
138: * the status of the message preparation. {@link SnmpConstants#SNMP_MP_OK}
139: * is returned if on success, otherwise any of the
140: * <code>SnmpConstants.SNMP_MP_*</code> values may be returned.
141: */
142: int prepareResponseMessage(int messageProcessingModel,
143: int maxMsgSize, int securityModel, byte[] securityName,
144: int securityLevel,
145: /* the following parameters are given in ScopedPDU
146: byte[] contextEngineID,
147: byte[] contextName,
148: */
149: PDU pdu, int maxSizeResponseScopedPDU,
150: StateReference stateReference,
151: StatusInformation statusInformation,
152: BEROutputStream outgoingMessage) throws IOException;
153:
154: /**
155: * Prepare data elements from an incoming SNMP message as described in
156: * RFC3412 §7.2.
157: *
158: * @param messageDispatcher
159: * the <code>MessageDispatcher</code> instance to be used to send reports.
160: * Thus, <code>messageDispatcher</code> is typically the calling module.
161: * @param transportAddress
162: * the origin transport address.
163: * @param wholeMsg
164: * the whole message as received from the network.
165: * @param messageProcessingModel
166: * returns the message processing model (typically the SNMP version).
167: * @param securityModel
168: * returns the security model ID (see {@link SecurityModel}.
169: * @param securityName
170: * returns the principal.
171: * @param securityLevel
172: * returns the requested security level (see {@link SecurityLevel}).
173: * @param pdu
174: * returns SNMP protocol data unit (the payload of the received message).
175: * @param sendPduHandle
176: * returns the handle to match request.
177: * @param maxSizeResponseScopedPDU
178: * returns the maximum size of the scoped PDU the sender can accept.
179: * @param statusInformation
180: * returns success or error indication. When an error occured, the error
181: * counter OID and value are included.
182: * @param stateReference
183: * returns the state reference to be used for a possible response. On input
184: * the stateReference may contain information about the transport mapping
185: * of the incoming request. This allows the
186: * <code>MessageProcessingModel</code> to send reports over the same
187: * transport as it received them.
188: * @throws IOException
189: * if the decoding of the message failed.
190: * @return int
191: * the status of the message preparation. {@link SnmpConstants#SNMP_MP_OK}
192: * is returned on success, otherwise any of the
193: * <code>SnmpConstants.SNMP_MP_*</code> values may be returned.
194: */
195: int prepareDataElements(MessageDispatcher messageDispatcher,
196: Address transportAddress, BERInputStream wholeMsg,
197: Integer32 messageProcessingModel, Integer32 securityModel,
198: OctetString securityName, Integer32 securityLevel,
199: /* the following parameters are given in ScopedPDU
200: byte[] contextEngineID,
201: byte[] contextName,
202: */
203: MutablePDU pdu, PduHandle sendPduHandle,
204: Integer32 maxSizeResponseScopedPDU,
205: StatusInformation statusInformation,
206: MutableStateReference stateReference) throws IOException;
207:
208: /**
209: * Checks whether the supplied SNMP protocol version is supported by this
210: * message processing model.
211: * @param snmpProtocolVersion
212: * the SNMP protocol version.
213: * @return
214: * <code>true</code> if the supplied SNMP protocol is supported,
215: * <code>false</code> otherwise.
216: */
217: boolean isProtocolVersionSupported(int snmpProtocolVersion);
218:
219: /**
220: * Release the state reference associated with the supplied
221: * <code>PduHandle</code>.
222: * @param pduHandle
223: * a <code>PduHandle</code>.
224: */
225: void releaseStateReference(PduHandle pduHandle);
226: }
|