| Solstice Enterprise Manager 4.1 C++ API Reference |
|
Common API
This chapter describes classes and their member functions that can be used by all the Application Programming Interface (API) libraries.
This chapter comprises the following topics:
- Section 2.1 Common API Classes
- Section 2.2 Class Categories
- Section 2.3 Variable Types
- Section 2.4 Class Descriptions
2.1 Common API Classes
TABLE 2-1 lists the classes described in this chapter.
TABLE 2-1 Common API Classes Address Class Used to store an address Arraydeclare Macro Used to create a class whose structure is an array Asn1ParsedValue Class Represents a parsed Asn1Value that is invalidated Asn1Tag Class Defines an ASN.1 tag class and value Asn1Type Class Used to implement ASN.1 encoding and decoding Asn1Value Class Defines storage and operations for ASN.1 values Blockage Class Used to manage blocked callback events Callback Class Used to post and dispatch callback events Command Class Used to define unique commands Config Class Used to manage database configuration file defaults DataUnit Class Used as a basic storage unit for data Dictionary Class Provides facilities to classes created by the Dictionarydeclare macro GenInt Class Represents integers of arbitrary size Hash Class HashImpl Class Used to implement a dynamically growing hash table Hashdeclare Macro Used to create a hash table class Hdict Class Provides facilities to classes created by the Hdictdeclare macro Oid Class Defines a container for an object identifier Queue Class Queuedeclare Macro Used to create a queue class with the specified type. Timer Class Used to schedule events to occur after a specific interval
2.2 Class Categories
There are five general categories of classes, as shown in TABLE 2-2, that can be used with the Application Programming Interface.
- Address Classes
- ASN.1 Classes
- Scheduling and Callback Handling Classes
- Array and Hashing Class
- Dictionary Macro Classes
2.3 Variable Types
The basic types of variables shown in TABLE 2-3 are declared in the /opt/SUNWconn/em/include/pmi/basic.hh file.
2.4 Class Descriptions
TABLE 2-4 lists each Common API Class with a brief description of each class.
TABLE 2-4 Common API Classes Address Class Used to store an address Asn1ParsedValue Class Represents a parsed Asn1Value that has not be validated against a type. Asn1Tag Class Defines an ASN.1 tag class and value Asn1Type Class Used to implement ASN.1 encoding and decoding Asn1Value Class Defines storage and operations for ASN.1 values Blockage Class Used to manage blocked callback events Callback Class Used to post and dispatch callback events Command Class Used to define unique commands Config Class Used to manage database configuration file defaults DataUnit Class Used as a basic storage unit for data Dictionary Class Provides facilities to classes created by the Dictionarydeclare macro HashImpl Class Used to implement a dynamically growing hash table Hdict Class Provides facilities to classes created by the Hdictdeclare macro Hrefdict Class Provides facilities to classes created by the Hrefdictdeclare macro Oid Class Defines a container for an object identifier
2.5 Address Class
This class defines a structure used to contain an address. An instance of Address contains an address class, an address tag, and an address value. The address tag is used with the value to form an address. The Address class distinguishes between members of the enum AddressClass, as shown in TABLE 2-5.
TABLE 2-5 AddressClass Data Members AC_DEFAULT Route by object instance in request AC_APP Application address AC_DIR_SERVICE A directory service for resolution AC_PRIMITIVE Protocol driver address
The address tag can be one of the values shown in TABLE 2-6.
TABLE 2-7 lists the well-known address types for directory services.
TABLE 2-7 Directory Services AT_DS_OBJ_INST 0 Object Instance AT_DS_APP_ENT_TITLE 1 Application Entity Title AT_DS_DOMAIN_NAME 2 Domain
TABLE 2-8 lists the Address class public variables.
TABLE 2-8 Address Public Variables AddressClass aclass The address class AddressTag atag The address tag DataUnit aval ASN.1-encoded address value
2.5.1 Constructor
Default for a class is AC_DEFAULT. Default for a tag is AT_PRIM_OAM.
2.5.2 Operator
The operator above creates an instance of Address having the same values as the argument addr.
This operator returns TRUE if the two Addresses have the same class, tag, and value.
This operator returns TRUE unless the two Addresses have the same class, tag, and value.
2.5.3 Address Member Functions
This section describes the member functions of the Address class.
These function calls append a record of the Address's class, tag, and value to the file fp or to the debug stream deb.
2.6 Arraydeclare Macro
#include <omi/array.hh>
The Arraydeclare macro declares a class whose name is formed from "Array" followed by its argument. This permits creation of a class whose structure is an array with each element containing an instance of the class named in its argument. Because an Array object thus created is confined to the scope in which the macro is used, it deletes itself when the scope is exited. This obviates the need for "array delete" statements before return, since arrays are automatically deleted at return.
The definition for the overloaded = operator assures that only one Array is in charge of a piece of memory at a time. It does this by swiping the array pointer from the other Array. If you want to have multiple people referencing the same array, you must pass a reference to the Array object, or sneak the pointer out of the Array object. Be careful not to place the pointer in another Array object; that would cause a double delete. The array's size is defined as a "pseudo const" although the class itself cheats on the const-ness, it expects the user not to.
Because the subscripting operator is defined in-line, there should be no extra overhead from using this class instead of subscripting directly. If you want the subscripting operator to do extra checking, define SUBSCRIPTCHECK appropriately.
This macro provides validation of the subscripts used in indexing an array, but only while operating in debug mode.
The following are array declarations pre-defined in array.hh:
2.7 Asn1ParsedValue Class
Inheritance: class Asn1ParsedValue
Data Members: No public data members are declared in this class.
An Asn1ParsedValue represents a parsed Asn1Value that has not yet been validated against a type. This form is used to hold a parsed value until its type has been completely determined. The Asn1ParsedValue is represented internally by an Asn1Value of the type ASN-PARSED-VALUE.
Classes used in various aspects of the implementation of ASN.1 encoding and decoding rely on the ISO specifications of Abstract Syntax Notation One. TABLE 2-9 lists the Asn1ParsedValue public functions.
2.7.1 Constructors
These are constructors for the Ans1ParsedValue class.
2.7.2 Asn1ParsedValue Operator Overloading
These are the operators for the Ans1ParsedValue class.
This operator is provided so that you can say "if (!Asn1ParsedValue)..."
2.7.3 Asn1ParsedValue Member Functions
This section describes the member functions of the Asn1ParsedValue class.
format_value
const DataUnit def_mod = DataUnit(),
Asn1Flags flags = 0 ) constThis function writes into the buffer buf a string representation of the Asn1ParsedValue. The representation must have a length no greater than buf_len characters, including indent leading blanks. This function returns OK if the value can be extracted and fits in buffer length provided.
get_parsed_val
This function returns the encoded parsed value as an Asn1Value.
get_real_val
Boolean indefinite = FALSE) constThis function, given an Asn1Type, returns an Asn1Value representation of the value.
2.8 Asn1Tag Class
Asn1Tag is a class that defines an ASN.1 tag class and an ASN.1 value for a tag. An ASN.1 tag value is defined as a U32 value. The enumeration Asn1TagClass (see Section 2.24.7 Asn1TagClass") has the following possible values:
Following are some predefined macros which assist in making tags of specific classes. Each of the macros below creates an Asn1Tag instance of tag number v.
Classes used in various aspects of the implementation of ASN.1 encoding and decoding rely on the ISO specifications of Abstract Syntax Notation One. For details, please consult the sources cited in the standards document.
TABLE 2-10 lists the Asn1Tag class public variables.
TABLE 2-10 Asn1Tag Public Variables Asn1TagClass tclass The Asn1Tag class Asn1TagValue value The value of the tag within the class
TABLE 2-11 lists the Asn1Tag public functions.
TABLE 2-11 Asn1Tag Public Functions operator==() operator!=() size() Report the tag's size
2.8.1 Constructors
These are the constructors for the Asn1Tag class. The following constructor creates an instance of an Asn1Tag with a tag class of CLASS_UNIV and a tag value of 0.
This constructor creates an Asn1Tag with a tag class specified by cl and a tag value specified by val.
2.8.2 Asn1Tag Operator Overloading
This section describes the operators for the Asn1Tag class.
This operator compares the operand tags and returns nonzero if the two are equal, zero otherwise.
This operator compares the operand tags and returns nonzero if the two are different, zero otherwise.
2.8.3 Asn1Tag Member Functions
This section describes the member function of the Asn1Tag class.
size
This function call returns a U32 value containing the number of octets in the tag.
2.9 Asn1Type Class
Classes used in various aspects of the implementation of ASN.1 encoding and decoding rely on the ISO specifications of Abstract Syntax Notation One. For details, please consult the sources cited in the standards document.
Associated classes: Asn1Module, ATData, Asn1TypeEL, Asn1TypeE, Asn1TypeChoice, Asn1ParsedValue, and D3SyntaxData.
TABLE 2-12 lists Asn1Type public functions.
2.9.1 Constructors
Use the preceding constructor as the default constructor.
Use the preceding constructor to initialize from an Asn1Value representation of the Asn1Type.
Use the preceding constructor to construct BOOLEAN, OCTET_STRING, NULL,OBJECT_IDENTIFIER, and REAL entities. Asn1Kind has the following numeric definitions of enumerated data types.
Use the preceding constructor to initialize from an Asn1Value representation of the Asn1Type.
This constructor is initialized from the canonical text representation of the Asn1Type. Where module_name comes from the defined DataUnit module_name.
2.9.2 Destructor
2.9.3 Asn1Type Operator Overloading
This section describes operator overloading for Asn1Type.
This operator assigns the value of at to Asn1Type.
This operator tests whether Asn1Type is initialized.
This operator converts the Asn1Type to its Asn1Value representation.
This operator is provided so that you can say "if (!Asn1ParsedValue)..."
2.9.4 Asn1Type Member Functions
This section describes the member functions of the Asn1Type class.
add_tags
Boolean indefinite=FALSE)const ;This function call retags or adds tags to a value to make it conform to the type.
base_kind
This function call returns the underlying "kind" of the base type, recursing through TAGGED, SELECTION, DEFINED_TYPE, and SUBTYPE.
base_type
This function call retrieves the underlying "type" without respect to tagging or selection.
cmp
This function call determines the ordering of two Asn1Values. Returns a negative, 0 or positive value, as av1 is less than, equal to, or greater than av2. It throws an exception if an error is encountered.
determine_real_val
This function call takes (determines) an Asn1Value in parsed form and returns it in encoded form.
encode
This function call re-encodes the Asn1Value according to the specified encoding rules.
equivalent
This function call determines whether two Asn1Values are equivalent. It assumes that both values have been validated against the type.
find_all_components
This function call finds all the named components of the Asn1Type in the given Asn1Value. A component is a named field for SEQUENCE, SET, CHOICE, or a number for SEQUENCE OF, SET OF (0 is the count of the number of elements). Returns the type of the component in comp_types.
find_component
This function call finds the named component of the Asn1Type in the given Asn1Value. A component is a named field for SEQUENCE, SET, CHOICE, or a number for SEQUENCE OF, SET OF (0 is the count of the number of elements). Returns the type of the component in comp_type.
find_subcomponent
This function call finds the named subcomponent of the Asn1Type in the given Asn1Value. A subcomponent is a list of component names separated by a period.
format_type
This function call converts the Asn1Type to its canonical text representation.
format_value
This function converts an Asn1Value to its canonical text representation.
get_enum_identifiers()
This function returns a reference to an array of type Asn1NamedNumber, which holds the identifiers and associated values for the ASN.1 ENUMERATED type. If this function fails, it returns NOT_OK; otherwise, it returns OK.
get_range()
If this function is applied to an Asn1Type object that represents an ASN.1 type different from REAL or INTEGER, the function returns NOT_OK. If the invocation is successful, the function returns OK.
In addition, this function returns, by reference, the lower and upper range limits defined for a subtype of an INTEGER or REAL base type as variables of type Asn1ParsedValue, and the lower_open and upper_open Boolean variables that specify whether the corresponding range limit is open or closed. If the range limit is open, the lower_open and upper_open variables are set to TRUE; otherwise, these two variables are set to FALSE.
The X.208 standard defines ranges on INTEGER and REAL types. In addition, the X.208 standard uses MIN and MAX to specify lower and upper range limits respectively.
- MIN specifies the lower range limit defined for the parent type
- MAX specifies the upper range limit defined for the parent type
The PMI library encodes MIN and MAX as NULL Asn1ParsedValue values. Therefore, after invoking the get_range method, you must check whether the returned values for the upper and lower range limits are NULL, before attempting to decode them; see CODE EXAMPLE 2-1.
kind
This function call returns the "kind" of the type, i.e, BOOLEAN, INTEGER, SEQUENCE, DEFINED_VALUE, etc.
lookup_type
This function call returns the Asn1Type associated with a particular key value from an ANY DEFINED BY clause.
any_name is the name of the field of the sequence or set which is the ANY. defined_by_name is the name of the field storing the key. any_value is the value of the key.
An application can use this to discover the syntax of an attributes action, notification, parameter, and so on. For example, consider the type:
SEQUENCE {key OBJECT IDENTIFIERvalue ANY DEFINED BY KEY}The following expression would return the Asn1Type associated with this particular combination of the three arguments.
Asn1Value::lookup_type("value", "key", myOID)The method by which lookup_type() identifies a particular key-and-value combination can be provided explicitly by the static method register_any_handler() (below). After register_any_handler() has been invoked, lookup_type() first searches to find a function registered with an exact match in the any_name and defined_by_name fields.
Then it tries to find the function registered with a matching any_name but an empty defined_by_name field. Finally it tries to find a function with both names empty. If it can't find a function, or if the function can't locate the key, it returns a null Asn1Type as the result of lookup_type().
needs_explicit
This function call determines whether the Asn1Type requires explicit tagging.
parse_value
Asn1Flags = 0) const;This function call constructs an Asn1Value from a given string.
register_any_handler
const DataUnit &defined_by_name, AnyHandler handler);This function call specifies a key-to-value lookup function to be used by lookup_type (discussed above) for a particular combination of any_name and defined_by_name. Usually register_any_handler is invoked automatically by the PMI, but an application can invoke it explicitly.
See also: Asn1Type::unregister_any_handler() and Asn1Type::lookup_type().
remove_tags
This function call removes explicit tags from a value to get to the underlying base value.
set_add_members
This function call's arguments of and to are Asn1Values. Both of them are of the type identified by this Asn1Type. The unique members of the parameter of are inserted into to. One of the operations on SET_OF's.
Returns OK if the operation completed successfully, and NOT_OK otherwise (for example, if the Asn1Values were not both of the appropriate type).
set_intersects_with
Asn1Value &right) const;This function call's arguments left and right are Asn1Values. Both of them are of the type identified by this Asn1Type. One of the operations on SET_OF's.
Returns OK if components of left intersect with the components of right; that is, if any member of left is a member of right.
set_is_subset
This function call's arguments left and right are Asn1Values. Both of them are of the type identified by this Asn1Type. One of the operations on SET_OF's.
Returns OK if left is a subset of right; that is, if all the members of left are also members of right.
set_remove_dup_members
This function call's argument of is an Asn1Values of the type identified by this Asn1Type. The method removes any duplicate members from of. One of the operations on SET_OF's.
Returns OK if the operation completed successfully, and NOT_OK otherwise (for example, if the Asn1Values were not both of the appropriate type).
set_remove_members
This function call's arguments of and from are Asn1Values. Both of them are of the type identified by this Asn1Type. The method removes from from any members that are also present in of. One of the operations on SET_OF's.
Returns OK if the operation completed successfully, and NOT_OK otherwise (for example, if the Asn1Values were not both of the appropriate type).
unregister_any_handler
This function call undoes the effect of registering an AnyHandler function to work with lookup_type().
validate
This function call determines whether the specified Asn1Value is correctly formatted for the type.
validate_tag
This function call determines whether the specified Asn1Value has the correct tag for the type.
2.9.5 Related Types
AnyHandler
Declared in: asn1_type.hh
const DataUnit &defined_by_name, const Asn1Value &any_value)Declares a pointer to a function that looks up the Asn1Type of any_value, for a specific combination of any_name and defined_by_name.
2.10 Asn1Value Class
The Asn1Value class defines storage and operations for ASN.1 values. The class is capable of supporting multiple encoding schemes but presently only supports Basic Encoding Rules (BER) encoding and encoding in a native machine format. The Asn1Value class uses the DataUnit class to store encoded values. It can also use other classes to store special types of data. To store unencoded data, the Asn1Value class makes use of the protected class AVData (declared as a class but not otherwise specified in /opt/SUNWconn/em/include/pmi/asn1_val.hh).
The new and delete operators should not be used with the Asn1Value constructor and destructor functions because the class manages and allocates memory for the values it stores.
2.10.1 Assignment and Data Sharing
The = operator is overloaded to permit assignment of one instance of Asn1Value to another, so that both refer to the same data.
2.10.2 Type Conversion
The Asn1Value class facilitates type conversion by overloading the void *() and DataUnit operators.
2.10.3 Encoding Functions
The class defines a set of encoding functions. Each allocates an AVData instance to store a value in native machine encoding. If the Asn1Value previously contained a value, the memory for it is freed prior to allocating memory for the new value. These functions normally return OK, unless memory cannot be allocated for the new value, or under certain conditions noted in the descriptions that follow.
In general, the functions do not actually perform the encoding. In most cases, the Asn1Value class handles the encoding automatically the first time a function requests the data in an encoded form.
2.10.4 Encoding of a Distinguished Name
A distinguished name (DN) is represented by a constructed ASN.1 value. Consider a DN containing a single RDN that has an id=1.2.6.1.2.1.42.1.13 and a value=2. It would have the following format:
T L V SEQ x T L V SET y T L V SEQ z T L V OID a 1.2.6.1.2.1.78.1.13 (unencoded here) INT b 2
A code fragment to construct the distinguished name might be as follows:
2.10.5 Decoding Simple and Constructed Asn1Values
The Asn1Value class defines functions for decoding both simple and constructed Asn1Values. If a simple Asn1Value stores the value in the native machine format specified by the function, it is returned directly. If the value is stored in an encoded form, it is decoded, stored in the Asn1Value in the decoded form (it also still exists in the encoded form) and then returns the decoded value.
The functions return NOT_OK if called for an uninitialized Asn1Value, if called for a constructed value, or if called for an Asn1Value that is initialized but contains neither a decoded value or encoded value of the proper type.
Classes used in various aspects of the implementation of ASN.1 encoding and decoding rely on the ISO specifications of Abstract Syntax Notation One.
TABLE 2-13 lists Asn1Value functions.
TABLE 2-13 Asn1Value Functions constructed contents_size encoding incl_embedded size tag Query Asn1Value info encode_bits encode_boolean encode_enum encode_ext encode_int encode_null encode_octets encode_oid encode_oidstr encode_real encode_unsigned Encoding Asn1Value simple types decode_bits decode_boolean decode_enum decode_ext decode_int decode_octets decode_oid decode_real decode_unsigned Decoding Asn1Value simple types add_component make_explicit_tagged start_construct Encoding constructed Asn1Values delete_component first_component make_explicit_tagged next_component retag tagged_component Decoding constructed Asn1Values
2.10.6 Constructors
The following constructor allocates storage for an uninitialized ASN.1 value. Memory is not allocated for an AVData instance or for a DataUnit instance. The constructor creates an instance of an Asn1Value and sets its AVData pointer to 0.
No memory is allocated for the AVData instance or for a DataUnit in the constructor. If the encoding specified by the enc parameter matches the encoding specified for Asn1Value specified by the av parameter, the constructor instantiates an Asn1Value that points to the AVData contained in av (that is, it shares data with av). The reference count for the AVData instance pointed to by av is incremented. The default encoding for this constructor follows the Basic Encoding Rules (BER); currently only BER is supported.
The new operator should not be used with the above constructor function.
In the following constructor, memory is allocated for an AVData instance and the AVData instance is pointed at the DataUnit referenced by du. The reference count for the AVData instance created is set to one. No memory is allocated for the DataUnit. If the DataUnit specified by du is not valid, the pointer to the AVData instance is set to 0 and the memory for the AVData instance is deallocated.
The new operator should not be used with the above constructor function.
In the following constructor, memory is allocated for an AVData instance, but the DataUnit is shared with the DataUnit specified by the du parameter. The tag for the Asn1Value is set to the value specified by the tag parameter.
An Asn1Value can be a constructed type or a simple type. The constr parameter specifies whether the value specified by du is a constructed type. The type attribute of the newly instantiated Asn1Value is set to the value specified by constr.
The new operator should not be used with the above constructor function.
2.10.7 Destructor
The destructor decrements the reference count for the AVData instance pointed at by this Asn1Value. If the reference count goes to zero, the memory for the AVData instance is deallocated.
2.10.8 Asn1Value Operator Overloading
The = operator is overloaded so that one Asn1Value can share data with another Asn1Value. In the returned Asn1Value, the AVData pointer points to the same object as the AVData pointer in av. At the same time, assignment increases the reference count for the AVData unit that av points to.
If the instance of the Asn1Value that this function is operating was pointed to another AVData instance, the reference count for the instance is decremented; if the reference count goes to zero, the memory for instance is deallocated. The `=' operator returns a reference to an Asn1Value.
The operator void *() returns a void pointer to the AVData instance pointed to by the Asn1Value. This function performs a type conversion from an Asn1Value to a void * and can be used for implicit type conversions.
The operator DataUnit performs a type conversion from an Asn1Value to a DataUnit. If the Asn1Value is uninitialized, it returns a zero length DataUnit. This function can be used for implicit type conversions.
This allows you to say "if(!Asn1Value...)"
2.10.9 Asn1Value Member Functions
This section describes the member functions of the Asn1Value class.
add_component
This function call adds a component to this constructed Asn1Value. Alternatively,
returns OK if the operation completes normally, but NOT_OK if it encounters any of the following conditions:
- The Asn1Value has not been initialized;
- The Asn1Value is not a constructed type;
- The Asn1Value specified by component has not been initialized;
- The encoding of Asn1Value specified by component does not match the encoding of the Asn1Value to which the component is being added; or
- Memory cannot be allocated to add the new component.
The size of the constructed value is updated to reflect the size of the component(s) added.
compute_total_size
This function call reports on Memory size information.
constructed
This function call returns a boolean value indicating if the Asn1Value is a constructed type. (An Asn1Value can either be a constructed type or a simple type.)
contents_size
This function call sets the value of the sz parameter to the total size of a constructed Asn1Value. This function decodes each component of a constructed Asn1Value and returns the sum of the size of each DataUnit in the constructed value. If the Asn1Value does not decode properly, this function returns NOT_OK; otherwise it returns OK.
decode_bits
This function call decodes an encoded boolean value and stores the result in the DataUnit specified by the du parameter. The length of the bitstring, in bits, is assigned to the parameter specified by len.
This function call decodes an encoded boolean value and store the result in the Octet string pointed to by the val parameter. The length of the bit string, in bits, is assigned to the parameter specified by len.
decode_boolean
This function call decodes an encoded boolean value and stores the result in the variable referenced by val.
decode_enum
This function call decodes an enumerated value and stores the result in the I32 variable referenced by the val parameter.
Alternatively, this function call decodes an enumerated value and stores the result in the Asn1Int variable referenced by the val parameter.
decode_ext
This function call decodes an ASN1 external value, decomposing it into its components by setting the variables shown in TABLE 2-14 below.
TABLE 2-14 decode_ext Variable Descriptions Variable Description oid Its (optional) object identifier indirect Its (optional) indirect reference odes Its (optional) data-value descriptor encoding Its choice of the following, indicated by its tag: [0] ANY [1] Implicit octet string [2] Implicit bit string
decode_int
This function call decodes an encoded I32 value and stores the result in the variable referenced by val.
Alternatively, this function call decodes an encoded Asn1Int value and stores the result in the variable referenced by val.
decode_octets
This function decodes an encoded octet string.
This function call decodes an octet string of length len, and stores a copy of the decoded string into the Octet string pointed to by val.
decode_oid
These function calls decode an OID.
These function calls decode an OID (Object IDentifier). The argument can be the address of an OID, or a pointer to an octet string and the string's length. The decoding is formed by calling decode_octets. If the oid is not constructed, the function returns NOT_OK; otherwise it returns the result of decode_octets.
decode_real
These function calls decode an encoded real value and stores the result in the variable referenced by val, which takes the form of the specified type. The double integer is specified above.
For I32 scientific notation,
For Asn1Int scientific notation,
decode_unsigned
This function call decodes an encoded U32 value and stores the result in the variable referenced by val.
delete_component
This function call finds the component specified by zap, and removes it from the Asn1Value. The routine assigns the component that originally followed the deleted component to the Asn1Value specified by next. If no components remain following the one specified by zap, next is assigned an uninitialized Asn1Value, but the function still returns OK. Internally, this function performs lazy decoding, and only decodes values into components as they are needed.
Returns NOT_OK if the Asn1Value is not initialized, or if the Asn1Value can not be decoded into separate components.
drop_encoding
This function call will remove any cached values that have been encoded.
encode_bits
These function calls copy and store the value specified by val into the Asn1Value. The length of val, in bits, is specified by len. The bit value specified by val is expected to be passed to this function as an ASN.1 bit value.
If the Asn1Value previously contained a value, the storage for the previous value is deallocated before the new value is stored. The tag for the Asn1Value is set to the value specified by the tag parameter. The encoding of the Asn1Value defaults to BER.
Returns NOT_OK if memory cannot be allocated to store the encoded bit value.
encode_boolean
This function call stores a copy of the boolean value specified by the val parameter in the Asn1Value. If the Asn1Value previously contained a value, the storage for the previous value is deallocated before the new value is stored. The tag for the Asn1Value is set to the value specified by the tag parameter. The encoding of the Asn1Value is assumed to be BER.
encode_enum
These function calls store a copy of the value specified by val in the Asn1Value. If the Asn1Value previously contained a value, the storage for the previous value is deallocated before the new value is stored. The tag for the Asn1Value is shared which is set to the tag value specified by the tag parameter. The encoding of the Asn1Value defaults to BER.
Returns NOT_OK if storage cannot be allocated for the Asn1Value.
encode_ext
This function call inserts into this instance of Asn1Value an encoding of the EXTERNAL type, as defined by ISO 8824/X.208.
In that standard, the EXTERNAL type is defined as follows:
{direct-reference OBJECT IDENTIFIER OPTIONAL,indirect-reference INTEGER OPTIONAL,direct-reference ObjectDescriptor OPTIONAL,encoding CHOICE{single-ASN1-type [0] ANYoctet-aligned [1] IMPLICIT OCTET STRING,arbitrary [2] IMPLICIT BIT STRING}}The arguments that are not applicable to a particular case can be empty, provided that not all of tag, oid, indirect, odes, and encoding are empty.
TABLE 2-15 describes the encode_ext arguments:
TABLE 2-15 encode_ext Arguments tag Tag identifying the class of encoding oid Object identifier indirect Indirect reference odes Object descriptor encoding ASN1 encoding indefinite Whether this is an indefinite-length encoding
Returns OK if a value based on the arguments is successfully inserted into this ASN1 value.
encode_int
These function calls store a copy of the value specified by the val parameter in the Asn1Value. If the Asn1Value previously contained a value, the storage for the previous value is deallocated before the new value is stored. The tag for the Asn1Value is shared with is set to the tag value specified by the tag parameter. The encoding of the Asn1Value is set to the encoding specified by the enc parameter, but defaults to BER if not specified.
encode_minus_infinity
This function call encodes an Asn1Value having a tag specified by tag which may be a large negative number in the set of possible Asn1 numbers, larger than permitted by the limits of the compiler's integer type.
encode_null
This function call encodes a zero-length Asn1Value having a tag as specified by tag. The encoding of the Asn1Value defaults to BER. If the Asn1Value previously contained a value, the storage for the previous value is deallocated before the null value is stored. This function allocates storage for an AVData instance, but does not allocate storage for a DataUnit.
Returns NOT_OK if storage cannot be allocated for the AVData instance.
encode_octets
These function calls store a copy of the value specified by val in the Asn1Value. The length of the octet value, in octets, is specified by len. DataUnit has no specified length. If the Asn1Value previously contained a value, the storage for the previous value is deallocated before the new value is stored. The tag for the Asn1Value is set to the tag value specified by tag. The encoding of the Asn1Value defaults to BER. Returns NOT_OK if memory cannot be allocated to store the octet value.
The alternate form of the function call shares data with the DataUnit specified by val. The tag for the Asn1Value is set to the tag value specified by tag. The encoding of the Asn1Value defaults to BER. If the Asn1Value previously contained a value, the storage for the previous value is deallocated before the new value is stored.
Returns NOT_OK if memory cannot be allocated to store the portion of the Asn1Value that points to the shared DataUnit.
encode_oid
These function calls encode and store an OID as an ASN.1 oid. The OID can be either the address of an OID, or an octet string and length. The tag of the encoded oid is set to the tag specified by tag.
The encoding of the Asn1Value is BER (ENC_BER), which is also the default encoding. If any other encoding is specified, the method returns NOT_OK. It also returns NOT_OK if it cannot allocate the temporary storage needed as part of the encoding process.
encode_oidstr
This function call encodes and stores an integer dot string (for example, "1.3.6.1.2.1.78") as an ASN.1 oid. The tag of the encoded oid is set to the tag specified by tag. The encoding of the Asn1Value is BER (ENC_BER), which is also the default encoding. Any other encoding causes the function to return NOT_OK. The function also returns NOT_OK if it cannot allocate the temporary storage needed as part of the encoding process.
encode_plus_infinity
This function call encodes an Asn1Value having a tag specified by tag which may be a large positive number in the set of possible Asn1 numbers, larger than permitted by the limits of the compiler's integer type.
encode_real
The first function stores a copy of the value specified val into the Asn1Value. The second and third functions store the value derived from the mantissa, base, and exponent parameters. The tag for the Asn1Value is set to the value specified by tag. The Asn1Value's encoding defaults to BER. If the Asn1Value previously contained a value, the storage for the previous value is deallocated before the new value is stored.
Returns NOT_OK if storage cannot be allocated for the Asn1Value.
encode_unsigned
This function call stores a copy of the unsigned integer value specified by the val parameter in the Asn1Value. If the Asn1Value previously contained a value, the storage for the previous value is deallocated before the new value is stored. The tag for the Asn1Value is set to the tag value specified by the tag parameter. The encoding of the Asn1Value defaults to BER.
first_component
This function call assigns the first component in an Asn1Value to the Asn1Value specified by comp. The function returns NOT_OK if the Asn1Value is not initialized, or if the Asn1Value can not be decoded into separate components.
get_components
This function call finds all the components in an Asn1Value and assigns them to the Asn1Value array specified by comps.
The function returns NOT_OK if the Asn1Value is not initialized, or if the Asn1Value can not be decoded into separate components.
indefinite_length
This function call returns FALSE if the Asn1Value is not initialized, or if the Asn1Value can not be decoded into separate components or components of a specified length.
make_explicit_tagged
This function call re-constructs the Asn1Value with the input comp Asn1Value, and retags it with tag.
The function returns NOT_OK if the Asn1Value is not initialized, or if the Asn1Value can not be decoded into separate components.
next_component
This function call finds the component specified by prev, and assigns the component that follows it to the Asn1Value specified by the next parameter. If no components remain following the one specified by prev, next is assigned an uninitialized Asn1Value, but the function still returns OK. If no components remain, an empty Asn1Value is returned.
Internally, this function performs lazy decoding, and only decodes values into components as the components are needed. Returns NOT_OK if the Asn1Value is not initialized, or if the Asn1Value can not be decoded into separate components.
num_comps
This function call returns the number of components of the Asn1Value.
Each of the preceding function calls prints a formatted record of the Asn1Value class, appending it either to the file whose pointer is fp, or the debug stream deb, or to the character string pointed to by c.
retag
This function call replaces the Asn1Value's previous tag with the tag specified in the argument.
size
This function call returns a U32 value containing the length of an encoded Asn1Value. If the Asn1Value is uninitialized, it returns a length of zero. The size returned is the length DataUnit in which the encoded value is stored
start_construct
This function call initiates the creation of a constructed Asn1Value. The tag of the constructed type is set to the value specified by tag. If the Asn1Value previously contained a value, the storage for the previous value is deallocated before the new value is stored. The constructor sets a flag value to indicate whether the Asn1Value contains a constructed type; start_construct also sets the size of the value to zero.
Tag
This function call returns a reference to the Asn1Value's tag.
tagged_component
This function call checks to see if an Asn1Value contains only a single component. If the Asn1Value contains a single, initialized component, it assigns the component to the Asn1Value specified by the comp parameter.
If the Asn1Value contains more than one component, or is uninitialized, the function returns NOT_OK.
2.10.10 Related Global Functions
enc
The enc function returns an Asn1 encoded value of data based on the module and type information, or returns a NULL Asn1Value in case of an error.
getGeneralizedTime
The getGeneralizedTime function gets the local time as a generalized time. The gt parameter indicates where to store the generalized time, and tag specifies the tag to be used. The function returns OK when the generalized time is stored where specified in gt, or NOT_OK if there is an error.
2.11 Blockage Class
Inheritance: class Blockage
An instance of the Blockage class is a queue of callback events that are currently blocked and must be handled when they become unblocked. The class provides methods by which you can instruct the Blockage function on how to deal with the callbacks on its list as they become unblocked, or force their invocation at once.
The scheduler uses an instance of Blockage to maintain the scheduler queue, called sched_q, which is declared as extern.
sched_q
Declared in: sched.hh
The functions post_callback(), purge_callback(), purge_callback_handler(), and purge_callback_data() use sched_q, the extern instance of Blockage used to manage scheduler events.
Events in the scheduler queue are blocked only until the next time the scheduler runs. The scheduler dispatches callbacks before calling select() and before returning. Callbacks are invoked in the order in which they were posted (FIFO).
TABLE 2-16 Blockage Public Functions Post to a wait queue One new callback sleep Invoke All waiting callbacks wakeup
wakeup_nowInvoke Any matching callbacks wakeup Invoke Any callbacks with matching handler wakeup Invoke Any callbacks with matching data wakeup Invoke or purge Any callbacks with matching call data wakeup_call
purge_callRetrieve Number of callbacks in the queue size
2.11.1 Constructor
Establishes a new instance with an empty queue of callback events.
2.11.2 Blockage Member Functions
purge_call
Purges from the Blockage's queue those callbacks whose callback data matches cdata.
size
Returns the number of members in the blockage's queue.
sleep
Posts a callback to the Blockage's wait queue.
wakeup
This function invokes all of the Blockage's waiting callbacks.
Invokes the callback event identified by e.
Invokes any of the Blockage's callbacks whose handler matches handler.
Invokes any of the Blockage's callbacks whose data matches data.
wakeup_call
Invokes any of the Blockage's callbacks whose callback data matches cdata.
wakeup_now
Invokes immediately all waiting callback events in the Blockage's queue.
2.11.3 Related Global Functions
post_callback
Adds a Callback instance to the end of the scheduler's immediate callback queue, optionally with callback data cdata. The scheduler dispatches callbacks just before calling select() and just before returning. Callbacks will occur in the order posted.
purge_callback
This function purges any matching callbacks from the scheduler queue. The scheduler will not dispatch these callbacks the next time it is run.
purge_callback_data
This function removes all callbacks whose USER data matches the parameter data from the scheduler callback queue. It calls the (overloaded) operator == to do the comparison.
purge_callback_cdata
This function removes all callbacks whose CALL data matches the parameter data from the scheduler callback queue.
purge_callback_handler
This function purges all callbacks with matching handler from the scheduler queue.
post_fd_read_callback
The post_fd_read_callback function posts callback cb to the scheduler's read callback queue for file descriptor fd. When the scheduler detects (by select()) something ready to read on fd, the callback cb gets called.
post_fd_write_callback
The post_fd_write_callback function posts callback cb to the scheduler's write callback queue for file descriptor fd. When the scheduler detects (by select()) something ready to write on fd, the callback cb gets called.
post_fd_except_callback
The post_fd_except_callback function posts callback cb to the scheduler's exception callback queue for file descriptor fd. When the scheduler detects (by select()) any exception on fd, the callback cb gets called.
purge_fd_read_callback
The purge_fd_read_callback function calls FD_CLR on fd for the read mask. Any previously posted read callback will not get called by the scheduler.
purge_fd_write_callback
The purge_fd_write_callback function calls FD_CLR on fd for the write mask. Any previously posted write callback will not get called by the scheduler.
purge_fd_except_callback
The purge_fd_except_callback function calls FD_CLR on fd for the exception mask. Any previously posted exception callback will not get called by the scheduler.
purge_fd_callbacks
The purge_fd_callbacks function calls FD_CLR on fd for the read, write, and exception masks. Any previously posted read, write, or exception callbacks will not get called by the scheduler.
flush_events_callbacks
The flush_events_callbacks function allows applications to flush all events to the MIS by executing all callbacks in both scheduler read and write callback queues.
2.12 Callback Class
This class serves to post and dispatch callback events. Callbacks are declared by the application and posted to the scheduler by the various posting routines. A callback contains a function pointer specifying the handler to be called when the callback is eventually dispatched. When a callback handler is called, it is passed two pieces of data:
- user_data: The data placed in the Callback by the application
- call_data: Supplied by the routine dispatching the call (and can be NULL)
The scheduler keeps a queue of callbacks that should happen immediately. The scheduler routine dispatches these callbacks once the routine is entered, and again after it has dispatched all I/O and timeouts, in case the I/O or timeout callbacks scheduled any immediate callbacks themselves. Immediate callbacks occur in the order posted.
TABLE 2-17 Callback Public Variables CallbackHandler handler; The function the scheduler should call Ptr data; Data provided as argument to the callback function
TABLE 2-18 Callback Public Functions Operator overloading void* Invoke the callback directly exec
The callback class has the following typedef:
CallbackHandler
2.12.1 Constructor
Creates a callback instance with no handler or data.
Creates a callback instance with handler hand and data d.
2.12.2 Callback Operator Overloading
Returns TRUE if the two callbacks have equal data and the same context and the same callback handler; FALSE otherwise.
Returns a pointer to the callback's handler.
2.12.3 Callback Member Functions
exec
This function invokes the callback's handler with the callback's data and exec's call_data as arguments. The callback handler is executed, in its own Try block, with CATCHALL set to write a record of any exceptions to misc_stderr.print.
2.13 Command Class
Data Members: No public data members are declared in this class.
The Command class is used to define unique commands that can be passed between entities. The address of the Command object itself is used to identify it uniquely from all other Command objects. A Command object should only be defined at the global scope, and should always be const.
2.13.1 Constructor
This is the constructor for the Command class.
2.13.2 Operator
Following is the operator for the Command class. It casts a Command instance to an unsigned integer.
2.14 Config Class
Data Members: No public data members are declared in this class.
The Config class is used to define the orderly management of per-program or per-MIS defaults from configuration database files.
Each instance of the Config class has its own mapping of default names to default values. This mapping is loaded from a file defined either in the constructor or as a result of a call to the load member function.
Each line in the file is of the form:
Initial and trailing whitespace are ignored. A comment sign (`#') can be used to indicate that the remainder of the line should be ignored. TABLE 2-19 lists the Config public functions.
TABLE 2-19 Config Public Functions fetch Retrieve a default data value load Load a configuration database
2.14.1 Constructors
These are both constructors for the Config class.
2.14.2 Config Member Functions
This section describes the member functions of the Config class.
load
This function call loads the configuration file into the mapping table. If the environment variable env has been set, the function loads the file corresponding to env's value. If it is not set, the file $EM_MIS_HOME/file is used. If $EM_MIS_HOME is not set, the local directory copy of file is used.
This function call loads the configuration file file into the mapping table.
fetch
This function call looks up a mapping in the table. If the mapping does not exist, the value dflt is returned. Otherwise, returns a pointer to the string representing the value.
2.15 DataUnit Class
Data Members: No public data members are declared in this class.
The DataUnit class is a basic storage unit for data. Each instance of a DataUnit contains attribute information (defined by the DataUnit class definition) which includes a pointer to a chunk of memory allocated by the DataUnit for the storage of data.
The allocated storage provided by the DataUnit is typically allocated when the DataUnit is instantiated, but can also be reallocated when a value is assigned to a DataUnit. A DataUnit can be referenced (or shared) by a number of attributes or variables. Each DataUnit maintains a count of the number of attributes or variables that reference it.
When a DataUnit is created, its reference count is set to one. The count is incremented each time another value references it, and is decremented each time another value dereferences it. When the reference count goes to zero, the storage allocated for the DataUnit is deallocated. Each DataUnit also keeps track of the amount of dynamic memory it has allocated for storing data.
TABLE 2-20 lists the DataUnit class public functions.
TABLE 2-20 DataUnit Public Functions Octet* * [] = == != Operator overloading size Description of the DataUnit cmp Compare two DataUnits for sorting copy catenate Create a new data unit from an existing one,
or from two existing onesfragment copyin copyout Set or get a portion of the DataUnit chp Data as a character string
2.15.1 Constructors
This section describes the constructors for the DataUnit class.
This constructor creates an instance of a DataUnit, but does not allocate any memory for storing data. The size of the DataUnit is set to zero.
This constructor creates an instance of a DataUnit and allocates the number of bytes of memory specified by size for storing data. If the data specified by the Octet *data parameter is non-null, size bytes of data are copied from the octet string specified by data to the newly allocated storage, and the size of the DataUnit is set to size.
This constructor creates an instance of DataUnit from a NULL terminated string str.
Note – The DataUnit instance points to the same memory as str and it is assumed that the memory pointed by str is valid and is not changed during the lifetime of the DataUnit instance being created.
Unlike DataUnit (char *str), this constructor does not allocate new memory and copy contents of str into it. (See DataUnit(char *str))
Note – This constructor does not make a deep copy of the data passed to it. The correct way to use RWCString.data() to construct a DataUnit is to type cast const char * to char * so that DataUnit will keep its own copy of chars in RWCString, otherwise DataUnit will share the same data (chars) with RWCString. When RWCString goes out of scope, the data in RWCString gets destroyed, the DataUnit is still trying to use that data which has been destroyed by RWCString.
This constructor creates an instance of DataUnit but does not allocate any storage for it. The new DataUnit points at the storage allocated for the DataUnit identified by du. The reference count for the shared memory is incremented to reflect the additional DataUnit that is now pointing to it.
Note – The DataUnit instance points to the same memory as du and it is assumed that the memory pointed by du is valid and is not changed during the lifetime of the DataUnit instance being created.
This constructor creates an instance of DataUnit which points at the storage associated with data. Its length is indicated by size.
Note – This constructor does not make a deep copy of the data passed to it. The correct way to use RWCString.data() to construct a DataUnit is to type cast const char * to char * so that DataUnit will keep its own copy of chars in RWCString, otherwise DataUnit will share the same data (chars) with RWCString. When RWCString goes out of scope, the data in RWCString gets destroyed, the DataUnit is still trying to use that data which has been destroyed by RWCString.
This constructor creates an instance of DataUnit and allocates storage of length size bytes. Each byte of the allocated storage is assigned the value fill.
This constructor creates an instance of DataUnit with storage sufficient to hold a duplicate of str (assumed to be null-terminated), which is copied to the DataUnit. The DataUnit points to the same area of memory as const char *str; this assumes that the string could change.
2.15.2 Destructor
This destructor decrements the reference count for the (potentially) shared memory region used to store data for the DataUnit. If the reference count reaches zero, the memory used to store data is deallocated.
2.15.3 DataUnit Operator Overloading
This sections describes the operators for the DataUnit class.
This operator returns a pointer to the first Octet of allocated storage in the DataUnit.
This operator returns a reference to the storage allocated for the DataUnit specified by du. The reference count for the storage is incremented. If the DataUnit (*this) previously pointed to allocated storage, the reference count for that storage is decremented, and if the reference count reaches zero, the storage is deallocated.
This operator returns a reference to the first Octet of allocated storage in the DataUnit. This operator triggers an assertion failure if the DataUnit is uninitialized.
These operators return a reference to the Octet of allocated storage that is index bytes past the first byte of storage allocated for the DataUnit. The first byte of allocated storage would have an index value of 0; the second byte, an index value of 1; the third byte, an index value of 2; and so on. This operator triggers an assertion failure if the value specified by the index parameter is greater then the size of the allocated storage, or if the DataUnit is uninitialized.
This operator compares the DataUnit specified by du to a previously defined DataUnit, and returns a nonzero integer if the two are equivalent. Similar functionality is found in the cmp member function.
This operator compares the contents of the DataUnit with str. If they are the same, the function returns 1. If they differ, it returns 0.
This operator compares the DataUnit specified by du to a previously defined DataUnit, and returns a nonzero integer if the two are not equivalent. Similar functionality is found in the cmp member function.
This operator compares the contents of the DataUnit with str. If they are the same, the function returns 0. If they differ, it returns 1.
2.15.4 DataUnit Member Functions
This sections describes the member functions of the DataUnit class.
catenate
This function call constructs a DataUnit and allocates it dynamic storage equal to the size of the dynamic storage of du1, plus the size of the dynamic storage for du2. The catenate function then copies the allocated storage from du1, followed by the storage from du2, to the newly allocated storage. The function then returns the new DataUnit.
chp
This function call returns a pointer to a character string containing a representation of the DataUnit's data. The representation does not have a trailing newline character.
cmp
This function call performs a machine-dependent comparison of the two DataUnit's specified by du1 and du2. The function returns a result in the same way as strcmp: that is, the result is 0 if the two DataUnit's compare equal, Ð-1 if du1 is lexicographically less than du2, and 1 if du1 is lexicographically greater than du2.
copy
This function call copies data from the DataUnit specified by du to the DataUnit specified by *this. Data is copied from du starting from an offset into du's allocated storage specified by du_pos. The data is copied to *this starting at an offset into *this's allocated storage specified by pos. The number of octets copied is specified by ln. This function triggers an assertion failure if the number of octets to copy, specified by ln, plus the starting point specified by either du_pos or pos, is greater than the storage allocated for either du or *this, respectively.
copy
This function copies one DataUnit structure to another DataUnit structure.
copyin
This function call copies data from the location specified by the Octet *data parameter, into the dynamic memory allocated for the DataUnit. Data is copied into the allocated storage starting at a point that is pos bytes past the start of the allocated storage. The number of octets to copy is specified by ln. The function triggers an assertion failure if the starting position (specified by pos), plus the length to copy (specified by ln) is greater than the number of octets of storage allocated for the DataUnit.
copyout
This function call copies data from the DataUnit to location specified by the Octet *data parameter. Data is copied from the allocated storage of the DataUnit starting at a point that is pos bytes past the start of the allocated storage. The number of octets to copy is specified by ln. The function triggers an assertion failure if the starting position (specified by pos), plus the length to copy (specified by ln) is greater than the number of octets of storage allocated for the DataUnit.
equiv
This function call is used to compare two DataUnit pointers in a manner consistent with the declaration of the Hash macros. The result is zero if the DataUnit pointed by n1 is equal to the DataUnit pointed by n2, otherwise no zero.
fragment
This function call returns a DataUnit that points to a portion (or fragment) of the dynamic storage allocated for the DataUnit specified by *this. The fragment shares data with a portion of the storage allocated for the original DataUnit. The fragment starts st octets after the start of the allocated storage and extends for ln octets.
This function triggers an assertion failure either of the following occur:
- The start of the fragment, specified by st, plus the length of the fragment, specified by ln, is greater than the length of the allocated storage of DataUnit specified by *this.
- The DataUnit, specified by *this, is not initialized but st or ln is nonzero.
hash
This function call can be used when declaring Hash macros where a DataUnit is used as the key.
Each of the preceding function calls prints a formatted record of the DUclass, appending it either to the file whose pointer is fp, or the debug stream deb, or to the character string pointed to by c.
size
This function call returns the number of Octets of the storage allocated for the DataUnit.
unshare
This function call makes memory storage associated with a DataUnit not shared. Creates a private copy if it is currently shared.
2.16 Dictionary Class
The Dictionary class is the set of facilities that are provided to C++ classes created using the Dictionarydeclare macro. Dictionary tables are accessed in two ways: as indexable elements and using a key/value paradigm. Implicit in the definition of the dictionary is the lookup() function that provides the mechanism to map an arbitrary key value to an index in the array.
TABLE 2-21 Dictionary Protected Variables const T *table_ The internal table of elements U32 len_ The number of elements in the table
TABLE 2-22 Dictionary Functions lookup Look up an element num_elems Return the number of elements position Return the index of an element table Return a pointer to the table [] Operator overloading
2.16.1 Constructor
This constructor initializes a table pointer to t and assigns a length of ne.
2.16.2 Dictionary Operator Overloading
This function returns the nth element of the table where pos equals n.
2.16.3 Dictionary Member Functions
lookup
The lookup function, which must be implemented for each K and T that are defined for a usage of Dictionarydeclare(), returns a pointer to a table element of type T based on a key of type K.
num_elems
The num_elems function returns the number of elements in the table.
position
Given a pointer to the table element t, this function returns the index to the table.
table
This function returns a pointer to the table of elements managed within the Dictionary object.
2.17 GenInt Class
The GenInt class is used to represent integers of arbitrary size.
2.17.1 Constructors
GenInt() is the default constructor.
Constructs an instance of GenInt with initial value ival.
Constructs an instance of GenInt with initial value ival.
Constructs an instance of GenInt with initial value uval.
Constructs an instance of GenInt given the human readable string format in two's complement form.
Constructs an instance of GenInt given a DataUnit.
2.17.2 Copy Constructor
2.17.3 GenInt Member Functions
sign
The sign function returns the sign of the integer.
bits
The bits function returns the number of bits in the integer.
size
The size function returns the storage size, in bytes, of the integer.
div
The div function invokes the division operation.
format
The format function converts an integer to a character string.
encode
The encode function returns the two's complement form of the integer.
operator double
The operator double function returns the double value of GenInt.
operator I32
The operator I32 function returns the I32 value of GenInt. If GenInt is larger, it returns only the four most significant bytes.
operator U32
The operator U32 function returns the U32 value of GenInt. If GenInt is larger, it returns only the four most significant bytes.
operator +
Unary + operator.
&operator +=
The compound additive assignment operator.
operator -
Unary - operator.
&operator -=
&operator -=(const GenInt &v) {*this = *this - v;return *this;};The compound subtractive assignment operator.
operator !
Unary boolean operator. Returns TRUE if value is 0, FALSE otherwise.
operator *
The operator * function multiplies two GenInts.
&operator *=
The compound multiplicative assignment operator.
operator /
&operator /=
The compound division assignment operator.
operator %
&operator %=
The compound mod assignment operator.
operator <
operator >
operator <=
The "less than or equal" operator.
operator =>
The "greater than or equal" operator.
operator &
&operator &=
The compound bitwise AND assignment operator.
operator |
&operator |=
The compound bitwise OR assignment operator.
operator ^
&operator ^=
The compound bitwise XOR assignment operator.
operator ~
operator ==
operator !=
The binary not equal operator.
2.18 Hash Class
2.18.1 Hash Member Functions
fetch
or
This function fetches an element with the specified keytype or with specified keytype and hashval from the hash table.
store
or
This function stores an element with the specified keytype and valtype or with the specified keytype, valtype, and hashval into the hash table.
destroy
or
This function destroys an element with the specified keytype or with the specified keytype and hashval from the hash table.
iterate
This function iterates the hash table.
next
This function checks whether there is an element after the element with the specified keytype, valtype, and hashval from the hash table. If there is one, it returns TRUE, otherwise FALSE.
2.19 Hashdeclare Macro
Declared in: hash.hh
Hashdeclare is a macro used to create a hash table class that is specific to the types of its keys and values. To refer to the class thus created, use the Hash(keytype, valtype) macro (described below).
The arguments keytype and valtype are the names of declared types or classes. The arguments hashfun, eqfun, delkey, and delval are the names of functions required by the constructor for the HashImpl class.
Because the macro invokes functions defined in the HashImpl class, the class it produces is in a sense "derived" from HashImpl. Each of the member functions defined by Hashdeclare has a corresponding function of the same name defined by the HashImpl class. The macro and the HashImpl class also provide alternate calls to calculate the hashed values for you when you don't want to do it yourself.
2.20 HashImpl Class
The HashImpl class provides a template class used by the Hashdeclare() macro to implement a dynamically growing hash table. It maintains the private data structures that constitute the hash table.
The HashImpl class is intended to be somewhat primitive; it is normally hidden behind the HashDeclare macro. The HashImpl member functions have no idea what they're actually managing. All keys and values are passed to them as void* values.
For this reason, when the constructor for HashImpl is called, you must supply pointers to three functions:
- A function that takes two arguments of type void* and returns whether the two values are to be considered equal.
- A function (which might be NULL) to invoke when keys are to be destroyed. It is passed a single void* value.
- A function (which might also be NULL) to invoke when values are to be destroyed. It is also passed a single void* value.
These last two functions, if specified, are called whenever key/value pairs need to be deleted from the hash table, including when the entire table is destroyed.
It is often the case that the same key is used several times in a row. For this reason, all of the member functions that take a key argument also take an argument that is the hashed value of the key. The hash value needs to be recomputed only when the key changes. You can call any hash function you like, but it should return an unsigned 32-bit integer, hopefully with a uniformly pseudorandom distribution in the lowest n bits (where n is the number of bits necessary to index into a hash table big enough to hold the maximum number of entries, more or less). A sample hash function for null-terminated strings is supplied; see the member function, strhash().
In order for a key to match an entry in the table, its hashed value must first match the hashed value stored in the table entry. You could conceivably make use of this in a smart hash function to make otherwise identical keys behave as if they're different keys.
Variables: No public variables declared in this class.
TABLE 2-23 HashImpl Public Functions Fetch a value from the hash table fetch next Store a key and value in the hash table store Destroy a key-value pair destroy
2.20.1 Constructor
2.20.2 Destructor
2.20.3 HashImpl Member Functions
Apart from iterate(), the member functions of HashImpl are provided as implementations of the member functions of the specific hash class created by a use of the Hashdeclare macro.
clear
The preceding function call nulls out the class structure,
destroy
Deletes the key/value pair from the hash table. Returns the deleted value (which might have been destroyed, if a delval function was specified to the constructor).
fetch
Returns a pointer to the value associated with key and hashval.
iterate
Used internally by the class constructed by the Hashdeclare macro to reset the hash table's built-in iterator to the beginning.
next
Returns TRUE if more entries remain in the hash table. Sets pointer (Ptr) variables for the next key/value pair from the hash table, according to the table's built-in iterator. It also sets the corresponding hashval variable. It is legal to destroy the current value.
store
Stores a pointer to the value associated with the specified key and hashval, and returns that value. Any previous value associated with that key and hashval are destroyed. Returns the new value.
strhash
Declared in: hash.hh
The strhash() function is a sample hashing function for null-terminated strings. It could be used to calculate hash values for passing to the member functions of HashImpl, or its name could be passed to the Hashdeclare macro as the hash function for keys of the appropriate type.
2.21 Hdict Class
The Hdict class is the set of facilities provided to C++ classes created using the Hdictdeclare() macro. It utilizes the Hash mechanism to manage the lookup of elements in its table. It assumes that an appropriate Arraydeclare(T) and Hashdeclare(K,T) have preceded its declaration.
TABLE 2-24 Hdict Protected Variables Hash(K,T) *_hash; The internal hash table of elements Array(T) _array; The array of elements
TABLE 2-25 Hdict Public Functions lookup Lookup an element num_elems Return the number of elements table Return a pointer to the table position Return the index of an element set Initialize the array and the hash table
2.21.1 Constructors
This constructor creates an empty table.
This constructor creates a hashing dictionary by stealing the array associated with a and initializing an internal hash table.
2.21.2 Hdict (K,T) Operator Overloading
This function returns the nth element of the table where n equals pos.
2.21.3 Hdict Member Functions
lookup
The lookup function, which must be implemented for each K and T that are defined for a usage of Hdictdeclare(), returns a pointer to a table element of type T based on a key of type K.
num_elems
The num_elems function returns the number of elements in the table.
position
Given a pointer to the table element t, the position function returns the index to the table.
table
The table function returns a pointer to the table of elements managed within the Hdict Dictionary.
set
The set function allows you to populate your Hdict Dictionary with the specified array.
2.22 Hrefdict Class
The Hrefdict class is the set of facilities provided to C++ classes created using the Hrefdictdeclare() macro. It utilizes the Hash mechanism to manage the lookup of elements in its table. It assumes that an appropriate Arraydeclare(T) and Hashdeclare(K,T) have preceded its declaration.
TABLE 2-25 lists the Hrefdick protected variables.
TABLE 2-26 Hrefdict Protected Variables Hash(K,T) *_hash; The internal hash table of elements const T *table_ The internal table of elements U32 len_ The number of elements in the table
TABLE 2-27 lists the Hrefdict public functions.
TABLE 2-27 Hrefdict Public Functions lookup Lookup an element num_elems Return the number of elements table Return a pointer to the table position Return the index of an element set Initialize the hash table
2.22.1 Constructors
This constructor creates an empty table.
This constructor initializes a table pointer to t and assigns a length of ne.
2.22.2 Hrefdict (K, T) Operator Overloading
This function returns the nth element of the table where n equals pos.
2.22.3 Hrefdict Member Functions
lookup
The lookup function, which must be implemented for each K and T that are defined for a usage of Hrefdictdeclare(), returns a pointer to a table element of type T based on a key of type K.
num_elems
The num_elems function returns the number of elements in the table.
position
Given a pointer to the table element t, the position function returns the index to the table.
table
The table function returns a pointer to the table of elements managed within the Dictionary.
set
The set function allows you to populate your Hrefdict Dictionary with the table specified in the constructor.
2.23 Oid Class
Inheritance: class Oid : public DataUnit
Data Members: No public data members declared in this class
The Oid class defines a container for an object identifier. Each object identifier is a sequence of numbers that identify an object by an integer denoting its assigned position at each level of a tree-structured registry of object names.
Many of the properties of the Oid implementation (for example, data storage, sharing) are derived from DataUnit. TABLE 2-28 lists the Oid class public functions.
TABLE 2-28 Oid Public Functions = Operator overloading copy_oid format print Extract the entire oid num_ids Length of the oid get_id Extract a given id from within the oid add_id add_last_id append Add to the oid is_same_prefix Compare two ids values
2.23.1 Constructors
This section describes the constructors of the Oid class.
This constructor constructs an empty Oid.
Each of the preceding constructors construct an Oid from a particular representation of the list of IDs that comprise it.
This constructor constructs an object identifier whose first identifier is first_id and whose second identifier is second_id. The size of the allocated memory is size. The returned value place is used when appending new identifiers to the object identifier string (see add_id).
2.23.2 Oid Operator Overloading
This section describes the operators for the Oid class.
This operator shares the data storage associated with oid.
2.23.3 Oid Member Functions
This section describes the member functions of the Oid class.
add_id
This function call appends id to the Oid, and sets place to the current size (and hence the position at which id was inserted).
The Oid(U32, U32, U32, U32) constructor initializes place.
If need be, add_id() extends the Oid to accommodate the new id. (You could use the Oid(size) constructor to pre-extend the Oid instance to the desired size.)
add_last_id
This function call appends id to the last id in the Oid instance. Any additional storage is released.
append
This function call modifies front by appending the IDs contained in back. Returns OK if this is completed. Sets front_place to the last-written position in front (which is also the numbers of ids in front when the operation is complete).
copy_oid
This function call makes dest the same as src.
format
This function call writes to buf a string of length buf_len containing the formatted representation of the Oid. In the string, each ID is represented as decimal digits, and successive IDs are separated by a dot.
get_id
This function call extracts from the Oid its id_num'th id and stores it in id. (The first id is considered to be at position 1). To speed up subsequent access, stores at place the current position within the Oid, and initialize it to zero before the first use.
is_same_prefix
This function call compares two Oids to determine whether the one with the shorter sequence of IDs is a prefix of the other, and returns TRUE if it is. (If both Oids contain the same number of IDs, this boils down to asking whether they are equal.)
This function returns FALSE if the two Oids do not have the same prefix.
num_ids
This function call returns the number of IDs in the Oid instance.
Each of the preceding function calls print a formatted record of the Oid, appending it either to the file whose pointer is fp, or the debug stream deb, or to the character string pointed to by c.
2.24 Asn1TypeDefinedType Declarations
Following is a list of the Asn1TypeDefinedType declarations:
2.24.1 Asn1SubTypeKind
Following is the Asn1SubTypeKind declaration:
{ASK_NONE,ASK_SINGLE,ASK_CONTAINED,ASK_RANGE,ASK_PERMITTED,ASK_SIZE,ASK_INNER_SINGLE,ASK_INNER_MULTIPLE} ;2.24.2 Asn1SubTypeSize
Following is the Asn1SubTypeSize declaration:
2.24.3 Asn1Kind
Following is the Asn1Kind declaration:
enum Asn1Kind {AK_NONE,AK_BOOLEAN,AK_INTEGER,AK_BIT_STRING,AK_OCTET_STRING,AK_NULL,AK_SEQUENCE,AK_SEQUENCE_OF,AK_SET,AK_SET_OF,AK_CHOICE,AK_SELECTION,AK_TAGGED,AK_ANY,AK_OBJECT_IDENTIFIER,AK_ENUMERATED,AK_REAL,AK_SUBTYPE,AK_DEFINED_TYPE};2.24.4 Asn1TypeE
Following is the Asn1TypeE declaration:
2.24.5 Asn1TypeEL
Following is the Asn1TypeEL declaration:
2.24.6 Asn1TypeNN
Following is the Asn1TypeNN declaration:
2.24.7 Asn1TagClass
Following is the Asn1TagClass declaration:
{CLASS_UNIV,CLASS_APPL,CLASS_CONT,CLASS_PRIV} ;2.24.8 Asn1Tagging
Following is the Asn1Tagging declaration:
{TAG_EXPLICIT,TAG_IMPLICIT,} ;2.25 Queue Class
2.25.1 Queue Member Functions
enq
This function inserts an element at the end of a queue with the specified type.
prq
This function inserts an element at the head of a queue with the specified type.
inq
This function inserts the element nqe into a queue with the specified type before the element oqe.
apq
This function appends a queue to a queue with the specified type.
ppq
This function prepends a queue to a queue with the specified type.
deq
This function deletes the first element in a queue with the specified type.
rnq
This function rotates to the next element in a queue with the specified type.
rpq
This function rotates to the previous element in a queue with the specified type.
fiq
This function returns the first element in a queue with the specified type.
liq
This function returns the last element in a queue with the specified type.
exq
This function deletes an element in a queue with the specified type.
niq
This function finds the next element in a queue with the specified type.
piq
This function finds the previous element in a queue with the specified type.
nmq
This function returns the number of elements in a queue with the specified type.
2.26 Queuedeclare Macro
Declared in: queue.hh
The Queuedeclare macro is used to create a queue class with the specified type. Please see class queue(type) for more detail.
2.27 Timer Class
An event that is scheduled to occur after a specific interval is represented as an instance of the Timer class. Timer events are posted or removed from the timer queue by the functions post_timer(), purge_timer(), purge_timer_data(), and purge_timer_handler(). Each function is declared in sched.hh.
A Timer event is not dispatched before the specified interval has elapsed. However, it might have to wait longer if other processing has to happen when its interval has elapsed.
When the callback does occur, the timer automatically reposts itself if you specified a reload time in the Timer. (By default, the reload time is 0, meaning no reposting.) Both the invocation time and the reload time are specified in milliseconds.
The invocation time is the interval from the time at which you call the post_timer() routine. The reload time is the interval from the originally scheduled time (not from the time at which the callback was actually dispatched).
If the callback is delayed to the point that the reload interval has already elapsed, the scheduler skips a reload for an interval that has now elapsed, and schedules the reload for the next upcoming multiple of the reload interval.
Timers only guarantee that the callback does not run too early. There is no guarantee about it running too late, so don't try to use this to control real-time interactions.
Timers can be purged from the timer queue by matching on the enqueued object's handler, data, or both.
2.27.1 Default Constructor
Resets the time and reloads the timer.
2.27.2 Constructor
Resets the time and reloads the timer. This constructor has four arguments. The time (t) between now and the first callback; the reload time (re) between callbacks; the callback pointer (hand) to the functions which is executed; and the pointer (d) to the user data which is passed to the callback hand.
2.27.3 Operator
Compares the timers to determine whether they have the same callback function or not.
2.27.4 Related Global Functions
post_timer
Posts a timer event into the timer queue.
post_timer_handler
Posts from the timer queue any timer events whose handler matches the specified handler.
purge_timer
Purges from the timer queue any matching timer events.
purge_timer_data
Purges from the timer queue any timer events whose data matches data.
purge_timer_handler
Purges from the timer queue any timer events whose handler matches handler
getGeneralizedTime
The getGeneralizedTime function creates an ASN.1 encoded generalized time value for the current time.
|
Sun Microsystems, Inc. Copyright information. All rights reserved. |
Doc Set | Contents | Previous | Next | Index |