1 /*
   2  * Copyright (c) 2001, 2003, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 package com.sun.jmx.snmp.internal;
  26 
  27 import java.net.InetAddress;
  28 
  29 import com.sun.jmx.snmp.SnmpSecurityParameters;
  30 import com.sun.jmx.snmp.SnmpTooBigException;
  31 import com.sun.jmx.snmp.SnmpStatusException;
  32 import com.sun.jmx.snmp.SnmpPdu;
  33 import com.sun.jmx.snmp.SnmpMsg;
  34 
  35 import com.sun.jmx.snmp.SnmpUnknownSecModelException;
  36 import com.sun.jmx.snmp.SnmpBadSecurityLevelException;
  37 
  38 /**
  39 <P> An <CODE>SnmpIncomingRequest</CODE> handles both sides of an incoming SNMP request:
  40 <ul>
  41 <li> The request. Unmarshalling of the received message. </li>
  42 <li> The response. Marshalling of the message to send. </li>
  43 </ul>
  44  * <p><b>This API is a Sun Microsystems internal API  and is subject
  45  * to change without notice.</b></p>
  46  * @since 1.5
  47  */
  48 public interface SnmpIncomingRequest {
  49     /**
  50      * Once the incoming request decoded, returns the decoded security parameters.
  51      * @return The decoded security parameters.
  52      */
  53     public SnmpSecurityParameters getSecurityParameters();
  54      /**
  55      * Tests if a report is expected.
  56      * @return boolean indicating if a report is to be sent.
  57      */
  58     public boolean isReport();
  59     /**
  60      * Tests if a response is expected.
  61      * @return boolean indicating if a response is to be sent.
  62      */
  63     public boolean isResponse();
  64 
  65     /**
  66      * Tells this request that no response will be sent.
  67      */
  68     public void noResponse();
  69     /**
  70      * Gets the incoming request principal.
  71      * @return The request principal.
  72      **/
  73     public String getPrincipal();
  74     /**
  75      * Gets the incoming request security level. This level is defined in {@link com.sun.jmx.snmp.SnmpEngine SnmpEngine}.
  76      * @return The security level.
  77      */
  78     public int getSecurityLevel();
  79     /**
  80      * Gets the incoming request security model.
  81      * @return The security model.
  82      */
  83     public int getSecurityModel();
  84     /**
  85      * Gets the incoming request context name.
  86      * @return The context name.
  87      */
  88     public byte[] getContextName();
  89     /**
  90      * Gets the incoming request context engine Id.
  91      * @return The context engine Id.
  92      */
  93     public byte[] getContextEngineId();
  94     /**
  95      * Gets the incoming request context name used by Access Control Model in order to allow or deny the access to OIDs.
  96      */
  97     public byte[] getAccessContext();
  98     /**
  99      * Encodes the response message to send and puts the result in the specified byte array.
 100      *
 101      * @param outputBytes An array to receive the resulting encoding.
 102      *
 103      * @exception ArrayIndexOutOfBoundsException If the result does not fit
 104      *                                           into the specified array.
 105      */
 106     public int encodeMessage(byte[] outputBytes)
 107         throws SnmpTooBigException;
 108 
 109     /**
 110      * Decodes the specified bytes and initializes the request with the incoming message.
 111      *
 112      * @param inputBytes The bytes to be decoded.
 113      *
 114      * @exception SnmpStatusException If the specified bytes are not a valid encoding or if the security applied to this request failed and no report is to be sent (typically trap PDU).
 115      */
 116     public void decodeMessage(byte[] inputBytes,
 117                               int byteCount,
 118                               InetAddress address,
 119                               int port)
 120         throws SnmpStatusException, SnmpUnknownSecModelException,
 121                SnmpBadSecurityLevelException;
 122 
 123      /**
 124      * Initializes the response to send with the passed Pdu.
 125      * <P>
 126      * If the encoding length exceeds <CODE>maxDataLength</CODE>,
 127      * the method throws an exception.
 128      *
 129      * @param p The PDU to be encoded.
 130      * @param maxDataLength The maximum length permitted for the data field.
 131      *
 132      * @exception SnmpStatusException If the specified <CODE>pdu</CODE>
 133      *     is not valid.
 134      * @exception SnmpTooBigException If the resulting encoding does not fit
 135      * into <CODE>maxDataLength</CODE> bytes.
 136      * @exception ArrayIndexOutOfBoundsException If the encoding exceeds
 137      *   <CODE>maxDataLength</CODE>.
 138      */
 139     public SnmpMsg encodeSnmpPdu(SnmpPdu p,
 140                                  int maxDataLength)
 141         throws SnmpStatusException, SnmpTooBigException;
 142 
 143     /**
 144      * Gets the request PDU encoded in the received message.
 145      * <P>
 146      * This method decodes the data field and returns the resulting PDU.
 147      *
 148      * @return The resulting PDU.
 149      * @exception SnmpStatusException If the encoding is not valid.
 150      */
 151     public SnmpPdu decodeSnmpPdu()
 152         throws SnmpStatusException;
 153 
 154     /**
 155      * Returns a stringified form of the received message.
 156      * @return The message state string.
 157      */
 158     public String printRequestMessage();
 159     /**
 160      * Returns a stringified form of the message to send.
 161      * @return The message state string.
 162      */
 163     public String printResponseMessage();
 164 }