pdu.java

snmp4j

/*_############################################################################
  _##
  _##  SNMP4J - PDU.java
  _##
  _##  Copyright 2003-2005  Frank Fock and Jochen Katz (SNMP4J.org)
  _##
  _##  Licensed under the Apache License, Version 2.0 (the "License");
  _##  you may not use this file except in compliance with the License.
  _##  You may obtain a copy of the License at
  _##
  _##      http://www.apache.org/licenses/LICENSE-2.0
  _##
  _##  Unless required by applicable law or agreed to in writing, software
  _##  distributed under the License is distributed on an "AS IS" BASIS,
  _##  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  _##  See the License for the specific language governing permissions and
  _##  limitations under the License.
  _##
  _##########################################################################*/

package org.snmp4j;

import org.snmp4j.smi.*;
import org.snmp4j.asn1.*;
import java.io.IOException;
import java.io.OutputStream;
import java.util.Vector;
import org.snmp4j.smi.Integer32;
import org.snmp4j.mp.SnmpConstants;

/**
 * The <code>PDU</code> class represents a SNMP protocol data unit. The PDU
 * version supported by the BER decoding and encoding methods of this class
 * is v2.
 * <p>
 * The default PDU type is GET.
 *
 * @author Frank Fock
 * @version 1.1
 * @see PDUv1
 * @see ScopedPDU
 */
public class PDU implements BERSerializable {

  /**
   * Denotes a get PDU.
   */
  public static final int GET      = (BER.ASN_CONTEXT | BER.ASN_CONSTRUCTOR | 0x0);
  /**
   * Denotes a getnext (search) PDU.
   */
  public static final int GETNEXT  = (BER.ASN_CONTEXT | BER.ASN_CONSTRUCTOR | 0x1);
  /**
   * Denotes a response PDU.
   */
  public static final int RESPONSE = (BER.ASN_CONTEXT | BER.ASN_CONSTRUCTOR | 0x2);
  /**
   * Denotes a set PDU.
   */
  public static final int SET      = (BER.ASN_CONTEXT | BER.ASN_CONSTRUCTOR | 0x3);
  /**
   * Denotes a SNMPv1 trap PDU. This type can only be used with instances of the
   * {@link PDUv1} class.
   */
  public static final int V1TRAP   = (BER.ASN_CONTEXT | BER.ASN_CONSTRUCTOR | 0x4);
  /**
   * Denotes a SNMPv2c/v3 getbulk PDU.
   */
  public static final int GETBULK  = (BER.ASN_CONTEXT | BER.ASN_CONSTRUCTOR | 0x5);
  /**
   * Denotes a SNMPv2c/v3 inform PDU (unprecisely also known as a confirmed
   * notification).
   */
  public static final int INFORM   = (BER.ASN_CONTEXT | BER.ASN_CONSTRUCTOR | 0x6);
  /**
   * Denotes a SNMPv2c/v3 notification PDU (undistinguishable from
   * {@link #TRAP}).
   */
  public static final int TRAP     = (BER.ASN_CONTEXT | BER.ASN_CONSTRUCTOR | 0x7);
  /**
   * Denotes a SNMPv2c/v3 notification PDU (undistinguishable from
   * {@link #NOTIFICATION}).
   */
  public static final int NOTIFICATION = TRAP;
  /**
   * Denotes a SNMPv3 report PDU.
   */
  public static final int REPORT   = (BER.ASN_CONTEXT | BER.ASN_CONSTRUCTOR | 0x8);


  // Error status constants

  /**
   * Operation success (no error).
   */
  public static final int noError = SnmpConstants.SNMP_ERROR_SUCCESS;

  /**
   * PDU encoding is too big for the transport used.
   */
  public static final int tooBig = SnmpConstants.SNMP_ERROR_TOO_BIG;

  /**
   * No such variable binding name, see error index.
   */
  public static final int noSuchName = SnmpConstants.SNMP_ERROR_NO_SUCH_NAME;

  /**
   * Bad value in variable binding, see error index.
   */
  public static final int badValue = SnmpConstants.SNMP_ERROR_BAD_VALUE;

  /**
   * The variable binding is read-only, see error index.
   */
  public static final int readOnly = SnmpConstants.SNMP_ERROR_READ_ONLY;

  /**
   * An unspecific error caused by a variable binding, see error index.
   */
  public static final int genErr = SnmpConstants.SNMP_ERROR_GENERAL_ERROR;

  /**
   * The variable binding is not accessible by the current MIB view, see error
   * index.
   */
  public static final int noAccess = SnmpConstants.SNMP_ERROR_NO_ACCESS;

  /**
   * The variable binding's value has the wrong type, see error index.
   */
  public static final int wrongType = SnmpConstants.SNMP_ERROR_WRONG_TYPE;

  /**
   * The variable binding's value has the wrong length, see error index.
   */
  public static final int wrongLength = SnmpConstants.SNMP_ERROR_WRONG_LENGTH;

  /**
   * The variable binding's value has the wrong encoding, see error index.
   */
  public static final int wrongEncoding =
      SnmpConstants.SNMP_ERROR_WRONG_ENCODING;

  /**
   * The specified object does not exists and cannot be created,
   * see error index.
   */
  public static final int noCreation = SnmpConstants.SNMP_ERROR_NO_CREATION;

  /**
   * The variable binding's value is presently inconsistent with the current
   * state of the target object, see error index.
   */
  public static final int inconsistentValue =
      SnmpConstants.SNMP_ERROR_INCONSISTENT_VALUE;

  /**
   * The resource needed to assign a variable binding's value is presently
   * unavailable, see error index.
   */
  public static final int resourceUnavailable =
      SnmpConstants.SNMP_ERROR_RESOURCE_UNAVAILABLE;

  /**
   * Unable to commit a value, see error index.
   */
  public static final int commitFailed = SnmpConstants.SNMP_ERROR_COMMIT_FAILED;

  /**
   * Unable to undo a committed value, see error index.
   */
  public static final int undoFailed = SnmpConstants.SNMP_ERROR_UNDO_FAILED;

  /**
   * Unauthorized access, see error index.
   */
  public static final int authorizationError =
      SnmpConstants.SNMP_ERROR_AUTHORIZATION_ERROR;

  /**
   * The variable's value cannot be modified, see error index.
   */
  public static final int notWritable = SnmpConstants.SNMP_ERROR_NOT_WRITEABLE;

  /**
   * The specified object does not exists and presently it cannot be created,
   * see error index.
   */
  public static final int inconsistentName =
      SnmpConstants.SNMP_ERROR_INCONSISTENT_NAME;

  protected Vector variableBindings = new Vector();
  protected Integer32 errorStatus = new Integer32();
  protected Integer32 errorIndex = new Integer32();
  protected Integer32 requestID = new Integer32();
  protected int type = GET;

  /**
   * Default constructor.
   */
  public PDU() {
  }

  /**
   * Copy constructor.
   * @param other
   *    the <code>PDU</code> to copy from.
   */
  public PDU(PDU other) {
    variableBindings = (Vector) other.variableBindings.clone();
    errorIndex = (Integer32) other.errorIndex.clone();
    errorStatus = (Integer32) other.errorStatus.clone();
    type = other.type;
    requestID = (Integer32) other.requestID.clone();
  }

  /**
   * Adds a variable binding to this PDU.
   * @param vb
   *   a <code>VariableBinding</code> instance.
   */
  public void add(VariableBinding vb) {
    variableBindings.add(vb);
  }

  /**
   * Adds an array of variable bindings to this PDU.
   * @param vbs
   *   an array of <code>VariableBinding</code> instances. The instances in the
   *   array will be appended to the current list of variable bindings in the
   *   PDU.
   */
  public void addAll(VariableBinding[] vbs) {
    variableBindings.ensureCapacity(variableBindings.size()+vbs.length);
    for (int i=0; i<vbs.length; i++) {
      variableBindings.add(vbs[i]);
    }
  }

  /**
   * Gets the variable binding at the specified position.
   * @param index
   *    a zero based positive integer (<code>0 <= index < {@link #size()}</code>)
   * @return
   *    a VariableBinding instance. If <code>index</code> is out of bounds
   *    an exception is thrown.
   */
  public VariableBinding get(int index) {
    return (VariableBinding)variableBindings.get(index);
  }

  /**
   * Sets the variable binding at the specified position.
   * @param index
   *    a zero based positive integer (<code>0 <= index < {@link #size()}</code>)
   *    If <code>index</code> is out of bounds
   *    an exception is thrown.
   * @param vb
   *    a VariableBinding instance (<code>null</code> is not allowed).
   * @return
   *    the variable binding that has been replaced.
   */
  public VariableBinding set(int index, VariableBinding vb) {
    if (vb == null) {
      throw new NullPointerException("Variable binding must not be null");
    }
    return (VariableBinding)variableBindings.set(index, vb);
  }

  /**
   * Removes the variable binding at the supplied position.
   * @param index
   *    a position >= 0 and < {@link #size()}.
   */
  public void remove(int index) {
    variableBindings.remove(index);
  }

  /**
   * Gets the number of variable bindings in the PDU.
   * @return
   *    the size of the PDU.
   */
  public int size() {
    return variableBindings.size();
  }

  /**
   * Gets the variable binding vector.
   * @return
   *    the internal <code>Vector</code> containing the PDU's variable bindings.
   */
  public Vector getVariableBindings() {
    return variableBindings;
  }

  /**
   * Remove the last variable binding from the PDU, if such an element exists.
   */
  public void trim() {
    if (variableBindings.size() > 0) {
      variableBindings.removeElementAt(variableBindings.size() - 1);
    }
  }

  /**
   * Sets the error status of the PDU.
   * @param errorStatus
   *    a SNMP error status.
   * @see SnmpConstants
   */
  public void setErrorStatus(int errorStatus) {
    this.errorStatus.setValue(errorStatus);
  }

  /**
   * Gets the error status of the PDU.
   * @return
   *    a SNMP error status.
   * @see SnmpConstants
   */
  public int getErrorStatus() {
    return errorStatus.getValue();
  }

  /**
   * Gets a textual description of the error status.
   * @return
   *    a String containing an element of the
   *    {@link SnmpConstants#SNMP_ERROR_MESSAGES} array for a valid error status.
   *    "Unknown error: <errorStatusNumber>" is returned for any other value.
   */
  public String getErrorStatusText() {