pasn.h

pwlib源码库

/*
 * pasn.h
 *
 * Abstract Syntax Notation 1 classes for support of SNMP only.
 *
 * Portable Windows Library
 *
 * Copyright (c) 1993-2002 Equivalence Pty. Ltd.
 *
 * The contents of this file are subject to the Mozilla Public License
 * Version 1.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.mozilla.org/MPL/
 *
 * Software distributed under the License is distributed on an "AS IS"
 * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
 * the License for the specific language governing rights and limitations
 * under the License.
 *
 * The Original Code is Portable Windows Library.
 *
 * The Initial Developer of the Original Code is Equivalence Pty. Ltd.
 *
 * Contributor(s): ______________________________________.
 *
 * $Log: pasn.h,v $
 * Revision 1.13  2002/11/06 22:47:24  robertj
 * Fixed header comment (copyright etc)
 *
 * Revision 1.12  2002/09/16 01:08:59  robertj
 * Added #define so can select if #pragma interface/implementation is used on
 *   platform basis (eg MacOS) rather than compiler, thanks Robert Monaghan.
 *
 * Revision 1.11  1999/05/01 03:52:20  robertj
 * Fixed various egcs warnings.
 *
 * Revision 1.10  1999/03/09 08:01:46  robertj
 * Changed comments for doc++ support (more to come).
 *
 * Revision 1.9  1999/02/16 08:07:10  robertj
 * MSVC 6.0 compatibility changes.
 *
 * Revision 1.8  1998/11/30 02:50:54  robertj
 * New directory structure
 *
 * Revision 1.7  1998/09/23 06:19:44  robertj
 * Added open source copyright license.
 *
 * Revision 1.6  1997/08/20 08:48:56  craigs
 * Added GetString() to PASNNull
 *
 * Revision 1.5  1997/07/20 08:34:14  craigs
 * Added ASN NULL type
 *
 * Revision 1.4  1997/07/16 05:51:08  craigs
 * Added PASNString constructor with ptr and length
 *
 * Revision 1.3  1996/11/04 09:45:08  robertj
 * Fixed bug in IP number ASN type, should be binary not dot format string.
 *
 * Revision 1.2  1996/11/04 03:56:00  robertj
 * Added ASN types to class.
 *
 * Revision 1.1  1996/09/14 12:58:57  robertj
 * Initial revision
 *
 */

#ifndef _PASN_H
#define _PASN_H

#ifdef P_USE_PRAGMA
#pragma interface
#endif

#include <ptlib/sockets.h>

//
// define some types used by the ASN classes
//
typedef	PInt32		PASNInt;
typedef DWORD		PASNUnsigned;
typedef	DWORD           PASNOid;

class PASNObject;
class PASNSequence;

PLIST(PASNObjectList, PASNObject);


//////////////////////////////////////////////////////////////////////////

/** This class defines the common behviour of all ASN objects. It also contains
   several functions which are used for encoding common ASN primitives.

   This class will never be instantiated directly. See the <A>PASNInteger</A>,
   <A>PASNSequence</A>, <A>PASNString</A> and <A>PASNObjectID</A> classes for examples
   of ASN objects that can be created.

   Only descendants of this class can be put into the <A>ASNSequence</A> class.
*/
class PASNObject : public PObject
{
  PCLASSINFO(PASNObject, PObject)

  public:
    /** Value returned by the <A>GetType()</A> function to indicate the type of
       an ASN object
     */
    enum ASNType {
      Integer,		// ASN Integer object
      String,       // ASN Octet String object
      ObjectID,		// ASN Object ID object
      Sequence,		// ASN Sequence object
      Choice,		// ASN Sequence with discriminator
      IPAddress,    // ASN IPAddress object
      Counter,      // ASN Counter object
      Gauge,        // ASN Gauge object
      TimeTicks,    // ASN TimeTicks object
      Opaque,       // ASN Opaque object
      NsapAddress,  // ASN NsapAddress
      Counter64,    // ASN Counter64
      UInteger32,   // ASN Unsigned integer 32
	  Null,         // ASN Null
      Unknown,		// unknown ASN object type
      ASNTypeMax	// maximum of number of ASN object types
    };

    /** Return a value of type <A>enum ASNType</A> which indicates the type
       of the object
     */
    virtual ASNType GetType() const;


    /** Return the descriminator for Choice sequences
    */
    int GetChoice() const;

    /** Return a string giving the type of the object */
    virtual PString GetTypeAsString() const;

    /** Return the value of the ASN object as a PASNInt.

       This function will assert if the object is not a descendant of
       <A>PASNInteger</A>.
     */
    virtual PASNInt GetInteger () const;

    /** Return the value of the object as a PASNUnsigned

       This function will assert if the object is not a descendant of
       <A>PASNTimeTicks</A> or <P>PASNCounter</A>.
     */
    virtual PASNUnsigned GetUnsigned () const;

    /** Return the value of the object as a PString. This function can
       be use for all ASN object types
     */
    virtual PString GetString () const;

    /** Return the value of the object as a PString

       This function will assert if the object is not a descendant of
       <A>PASNSequence</A>.
     */
    virtual const PASNSequence & GetSequence() const;

    /** Return the value of the object as an IPAddress

       This function will assert if the object is not a descendant of
       <A>PASNIPAddress</A>.
     */
    virtual PIPSocket::Address GetIPAddress () const;

    /** Virtual functions used by the <A>PObject::operator<<</A> function to
       print the value of the object.
    */
    virtual void PrintOn(
      ostream & strm		// stream to print on
    ) const;

    /** Virtual function used to encode the object into ASN format */
    virtual void Encode(
      PBYTEArray & buffer	// buffer to encode into
    );

    /** Virtual function used to get the length of object when encoded into
       ASN format 
    */
    virtual WORD GetEncodedLength();

    /** Virtual function used to duplicate objects */
    virtual PObject * Clone() const;

    /** Encode an ASN length value */
    static void EncodeASNLength (
      PBYTEArray & buffer,		// buffer to encode into
      WORD length			// ASN length to encode
    );

    /** Return the length of an encoded ASN length value */
    static WORD GetASNLengthLength (
      WORD length			// length to find length of
    );

    /** Decode an ASN length in the buffer at the given ptr. The ptr is moved
       to the byte after the end of the encoded length.
     */
    static BOOL DecodeASNLength (
      const PBYTEArray & buffer,		// buffer to decode data from
      PINDEX & ptr,			// ptr to decode from
      WORD & len			// returned length
    );

    /** Encode a sequence header into the buffer at the specified offset. */
    static void EncodeASNSequenceStart (
      PBYTEArray & buffer,		// buffer to encode data into
      BYTE type,			// sequence type
      WORD length			// length of sequence data
    );

    /** Return the encoded length of a sequence if it has the specified length */
    static WORD GetASNSequenceStartLength (
      WORD length			// length of sequence data
    );

    /** Encode an ASN object header into the buffer */
    static void EncodeASNHeader(
      PBYTEArray & buffer,		// buffer to encode into
      PASNObject::ASNType type,		// ASN type of the object
      WORD length			// length of the object
    );

    /** Return the length of an ASN object header if the object is the specified length */
    static WORD GetASNHeaderLength (
      WORD length			// length of object
    );

    static void EncodeASNInteger    (
      PBYTEArray & buffer,		// buffer to encode into
      PASNInt data,			// value to encode
      PASNObject::ASNType type		// actual integer type
    );
    // Encode an ASN integer value into the specified buffer */

    static void EncodeASNUnsigned (
      PBYTEArray & buffer,		// buffer to encode into
      PASNUnsigned data,		// value to encode
      PASNObject::ASNType type		// actual integer type
    );
    // Encode an ASN integer value into the specified buffer */

    static WORD GetASNIntegerLength (
      PASNInt data			// value to get length of
    );
    // Return the length of an encoded ASN integer with the specified value 

    static WORD GetASNUnsignedLength (
      PASNUnsigned data			// value to get length of
    );
    // Return the length of an encoded ASN integer with the specified value 

    static BOOL DecodeASNInteger (
      const PBYTEArray & buffer,		// buffer to decode from
      PINDEX & ptr,			// ptr to data in buffer
      PASNInt & value,			// returned value
      ASNType type = Integer	        // actual integer type
    );
    // Decode an ASN integer value in the specified buffer 

    static BOOL DecodeASNUnsigned (
      const PBYTEArray & buffer,		// buffer to decode from
      PINDEX & ptr,			// ptr to data in buffer
      PASNUnsigned & value,		// returned value
      ASNType type = TimeTicks	        // actual integer type
    );
    // Decode an ASN integer value in the specified buffer 

  protected:
    /** Create an empty ASN object. Used only by descendant constructors */
    PASNObject();

    /** Table to map <A>enum ASNType</A> values to ASN identifiers */
    static BYTE ASNTypeToType[ASNTypeMax];

};


//////////////////////////////////////////////////////////////////////////

/** A descendant of PASNObject which is a simple ASN integer type.
 */
class PASNInteger : public PASNObject
{
  PCLASSINFO(PASNInteger, PASNObject)
  public:
    PASNInteger(PASNInt val);
    PASNInteger(const PBYTEArray & buffer, PINDEX & ptr);

    void PrintOn(ostream & strm) const;
    void Encode(PBYTEArray & buffer);
    WORD GetEncodedLength();