ax_sa_cr.c

wm PNE 3.3 source code, running at more than vxworks6.x version.

/* ax_sa_cr.c - ax_sa_cr.c routines */

/*
 *  Copyright 2000-2005 Wind River Systems, Inc.
 *  All rights reserved.  Provided under license only.
 *  Distribution or other use of this software is only
 *  permitted pursuant to the terms of a license agreement
 *  from Wind River Systems (and is otherwise prohibited).
 *  Refer to that license agreement for terms of use.
 */

/*
 *  Copyright 1994-1997 Epilogue Technology Corporation.
 *  Copyright 1998 Integrated Systems, Inc.
 *  All rights reserved.
 */

/*
 * $Log: ax_sa_cr.c,v $
 * Revision 1.4  2001/11/06 21:50:44  josh
 * second (and hopefully final) pass of new path hacking
 *
 * Revision 1.3  2001/11/06 21:20:03  josh
 * revised new path hacking
 *
 * Revision 1.2  2001/11/06 20:11:14  josh
 * updating include paths to include proper path to layout directory
 *
 * Revision 1.1.1.1  2001/11/05 17:47:41  tneale
 * Tornado shuffle
 *
 * Revision 9.5  2001/04/11 20:12:02  josh
 * merging changes from the kingfisher branch back onto
 * the trunk
 *
 * Revision 9.4  2001/01/19 22:22:17  paul
 * Update copyright.
 *
 * Revision 9.3.2.2  2001/03/12 22:08:09  tneale
 * Updated copyright
 *
 * Revision 9.3.2.1  2000/10/13 21:17:35  josh
 * function prototypes and static declarations to eliminate warnings
 * from the Tornado compiler
 *
 * Revision 9.3  2000/03/17 00:18:56  meister
 * Update copyright message
 *
 * Revision 9.2  1999/05/24 20:12:14  josh
 * 'compc' and 'compl' have been replaced by 'tcount' and 'tlist'
 * to avoid C++ compiler errors.
 *
 * Revision 9.1  1998/12/03 17:52:39  sar
 * Several routines were using a logical instead of a bitwise operator
 * when checking if the flag set was permitted.
 *
 * Revision 9.0  1998/10/16 22:10:58  sar
 * Update version stamp to match release
 *
 * Revision 8.2  1998/06/19 20:13:49  sar
 * make sure all files include asn1conf.h and snmp.h to pick up all of
 * the common code
 *
 * Revision 8.1  1998/02/25 04:51:19  sra
 * Update copyrights.
 *
 * Revision 8.0  1997/11/18 00:56:40  sar
 * Updated revision to 8.0
 *
 * Revision 1.1  1997/10/16 00:32:34  sar
 * The base files for the agentx protocol.
 * ax_core.c  - core encoding and decoding routines, both master and sub
 * ax_chunk.c - transform a byte stream into agentx packets, both
 * ax_index.c - support for the index reservation scheme, master
 * ax_ma.c    - master side routines, master
 * ax_mth.c   - method routines for the agentx mib, master
 * ax_sa.c    - sub agent side routines, sub
 * ax_sa_cr.c - packet creation code, mostly will be used on sub
 *
 */

/* [clearcase]
modification history
-------------------
01d,12may05,job  fix apigen comments
01c,18apr05,job  update copyright notices
01b,16feb05,job  apigen for documented APIs
01a,24nov03,job  update copyright information
*/

/*
DESCRIPTION
This library contains ax_sa_cr.c routines.

INCLUDE FILES: snmp.h, agentx.h
*/

#include <wrn/wm/snmp/engine/asn1conf.h>
#include <wrn/wm/snmp/engine/agentx.h>
#include <wrn/wm/snmp/engine/buffer.h>
#include <wrn/wm/snmp/engine/objectid.h>
#include <wrn/wm/snmp/engine/vbdefs.h>
#include <wrn/wm/snmp/engine/snmp.h>

#include <wrn/wm/util/layout/ldbglue.h>
#include <wrn/wm/util/layout/agentx.h>

/*******************************************************************************
*
* envoy_ax_pkt_create_all - create and populate an AgentX packet structure
* SYNOPSIS
*
* \cs
* ENVOY_AX_PKT_T *  envoy_ax_pkt_create_all
*     ( 
*     int         *  err, 
*     bits8_t        version, 
*     bits8_t        pdu_type, 
*     bits8_t        flags, 
*     bits32_t       session_id, 
*     bits32_t       packet_id, 
*     bits8_t        time-out, 
*     bits32_t       descr_len, 
*     bits8_t     *  descr, 
*     int            descr_dynamic, 
*     OBJ_ID_T    *  obj, 
*     bits8_t        prefix, 
*     bits8_t        priority, 
*     bits8_t        range_subid, 
*     OIDC_T         upper_bound, 
*     bits32_t       context_len, 
*     bits8_t     *  context, 
*     int            context_dynamic, 
*     bits8_t        close_reason
*     )
* \ce
*
* DESCRIPTION
*
* This routine creates and populates an AgentX packet structure. If you are 
* writing a subagent, you can use it to set options for a specific PDU type. If 
* a PDU type does not use a particular option, it is ignored. This routine is 
* used less frequently than the other AgentX packet creation routines.
*
* \&NOTE: Do not use this routine to create PDUs that have VarBinds or search 
* lists, specifically 'ENVOY_AX_INDEX_ALLOCATE', 'ENVOY_AX_INDEX_DEALLOCATE', 
* and 'ENVOY_AX_NOTIFY' PDUs.
*
* PARAMETERS
* \is
* \i <*err>
* Contain an error code when this routine fails.
* \i <version>
* Specify the AgentX version number. At this release, the only supported 
* version is 'ENVOY_AX_VERSION_1'.
* \i <pdu_type>
* Indicate which type of message you are trying to create. This routine 
* supports the following types: 'ENVOY_AX_ADD_AC', 'ENVOY_AX_CLOSE', 
* 'ENVOY_AX_OPEN', 'ENVOY_AX_PING', 'ENVOY_AX_REGISTER', 'ENVOY_AX_REMOVE_AC', 
* or 'ENVOY_AX_UNREGISTER'.
* \i <flags>
* Specify the bits for the flag word of the packet header. This routine 
* supports the following flags:
* \is
* \i 'ENVOY_AX_BIT_INSTANCE'
* Indicate that the item being registered is an instance of an object. Use this 
* flag only for 'ENVOY_AX_REGISTER' PDUs.
* \i 'ENVOY_AX_BIT_NDC'
* Select a non-default context supplied by the user. Do not use this flag for 
* 'ENVOY_AX_CLOSE' or 'ENVOY_AX_OPEN' PDUs.
* \i 'ENVOY_AX_BIT_BYTE_ORDER'
* Select network-byte order for encoding or decoding. Otherwise, host-byte 
* order is used.
* \ie
* \i <session_id>
* Indicate to which session this packet belongs. When a subagent first opens a 
* session, this value is 0. Afterward, this value is the session ID supplied by 
* the master.
* \i <packet_id>
* Specify a number that allows the requester to match responses to requests.
* \i <timeout>
* Indicate how long the master agent waits before timing out registration and 
* open requests.
* \i <descr_len>
* Specify the length in bytes of a descriptive field (<descr>), which is passed 
* to the master agent to describe the subagent in an open request or the agent 
* capabilities when adding an agent capabilities.
* \i <*descr>
* Specify the descriptive string.
* \i <descr_dynamic>
* Indicate whether the descriptive field (<descr>) is dynamic 
* ('BFL_IS_DYNAMIC') and should be freed when the packet is cleaned or not 
* ('BFL_IS_STATIC').
* \i <*obj>
* Specify the object ID to add or remove depending on the PDU type.
* \i <prefix>
* Currently unused.
* \i <priority>
* Specify the priority.
* \i <range_subid>
* Specify that the sub ID is allowed to range between the value set in <*obj> 
* and the value set in <upper_bound>. For example, the range {3, 1.3.6} where 
* <*obj> is 3 and <upper_bound> is 10, registers the following sub IDs: 
* [1.3.6], [1.3.7], [1.3.8], [1.3.9], and [1.3.10].
* \i <upper_bound>
* Specify the upper bound of a sub ID range. The lower bound is given by the 
* object id.
* \i <context_len>
* Indicate the length in bytes of the context string (<context>), which is 
* passed to the master agent when a non-default context is used.
* \i <*context>
* Specify the context string.
* \i <context_dynamic>
* Indicate whether context is dynamic ('BFL_IS_DYNAMIC') and should be freed 
* when the packet is cleaned or not ('BFL_IS_STATIC'). If you choose to use a 
* non-default context, set the 'ENVOY_AX_BIT_NDC' flag.
* \i <close_reason>
* Specify one of the following reasons given by the subagent for closing the 
* connection: 'ENVOY_AX_CLOSE_OTHER', 'ENVOY_AX_CLOSE_PARSE', 
* 'ENVOY_AX_CLOSE_PROTO', 'ENVOY_AX_CLOSE_TIMEOUTS', 'ENVOY_AX_CLOSE_SHUTDOWN', 
* and 'ENVOY_AX_CLOSE_MANAGER'.
* \ie
*
* RETURNS: If successful, this routine returns a pointer to the allocated 
* packet structure. Otherwise, it returns 0 and returns one of the following 
* values:
* \is
* \i 'ENVOY_AX_ALLOCATION_FAILURE'
* Unable to allocate an AgentX packet.
* \i 'ENVOY_AX_BAD_VALUE'
* The packet was badly formed or <ebuffp> did not match its expected size.
* \ie
*
* ERRNO: N/A
*
* SEE ALSO: envoy_ax_pkt_create_agent_caps(), envoy_ax_pkt_create_close(), 
* envoy_ax_pkt_create_open(), envoy_ax_pkt_create_ping(), 
* envoy_ax_pkt_create_registrations(), envoy_ax_pkt_create_variables()
*/
ENVOY_AX_PKT_T *
  envoy_ax_pkt_create_all(int      *err,
			  bits8_t   version,
			  bits8_t   pdu_type,
			  bits8_t   flags,
			  bits32_t  session_id,
			  bits32_t  packet_id,
			  bits8_t   timeout,
			  bits32_t  descr_len,
			  bits8_t  *descr,
			  int       descr_dynamic,
			  OBJ_ID_T *obj,
			  bits8_t   prefix,
			  bits8_t   priority,
			  bits8_t   range_subid,
			  OIDC_T    upper_bound,
			  bits32_t  context_len,
			  bits8_t  *context,
			  int       context_dynamic,
			  bits8_t   close_reason)
{
ENVOY_AX_PKT_T *ax_pkt;

/* test the version before we get the packet */
if ((version != ENVOY_AX_VERSION_1) ||
    (flags & (ENVOY_AX_BIT_NEW_INDEX | ENVOY_AX_BIT_ANY_INDEX))) {
    *err = ENVOY_AX_BAD_VALUE;
    return(0);
    }

/* get the packet */
ax_pkt = envoy_ax_pkt_allocate();
if (ax_pkt == 0) {
    *err = ENVOY_AX_ALLOCATION_FAILURE;
    return(0);
    }

/* put the generic stuff into the packet, some
   of the fields will be checked for validity later */
ax_pkt->version   = version;
ax_pkt->type      = pdu_type;
ax_pkt->flags     = flags;
ax_pkt->session_id = session_id;
ax_pkt->packet_id  = packet_id;

switch(pdu_type) {
    default:
        *err = ENVOY_AX_BAD_VALUE;
	envoy_ax_pkt_free(ax_pkt);
	return(0);

    case ENVOY_AX_OPEN:
	if (flags & (ENVOY_AX_BIT_INSTANCE | ENVOY_AX_BIT_NDC)) {
	    *err = ENVOY_AX_BAD_VALUE;
	    envoy_ax_pkt_free(ax_pkt);
	    return(0);
	    }

	ax_pkt->data.open_data.timeout = timeout;
	if (build_object_id(obj->num_components, obj->component_list,
			    &ax_pkt->data.open_data.sub_id)) {
	    *err = ENVOY_AX_ALLOCATION_FAILURE;
	    envoy_ax_pkt_free(ax_pkt);
	    return(0);
	    }
	EBufferPreLoad(descr_dynamic, &ax_pkt->data.open_data.descr,
		       descr, descr_len);
	break;
	
    case ENVOY_AX_CLOSE:
	if (flags & (ENVOY_AX_BIT_INSTANCE | ENVOY_AX_BIT_NDC)) {
	    *err = ENVOY_AX_BAD_VALUE;
	    envoy_ax_pkt_free(ax_pkt);
	    return(0);
	    }
	ax_pkt->data.reason = close_reason;
	break;

    case ENVOY_AX_REGISTER:
	ax_pkt->data.reg_data.timeout  = timeout;
	ax_pkt->data.reg_data.priority = priority;
	ax_pkt->data.reg_data.range    = range_subid;
	ax_pkt->data.reg_data.bound    = upper_bound;
	if (build_object_id(obj->num_components, obj->component_list,
			    &ax_pkt->data.reg_data.region)) {
	    *err = ENVOY_AX_ALLOCATION_FAILURE;
	    envoy_ax_pkt_free(ax_pkt);
	    return(0);
	    }
	if (flags & ENVOY_AX_BIT_NDC) {
	    EBufferPreLoad(context_dynamic, &ax_pkt->context,
			   context, context_len);
	    }
	break;

    case ENVOY_AX_UNREGISTER:
	if (flags & ENVOY_AX_BIT_INSTANCE)  {
	    *err = ENVOY_AX_BAD_VALUE;
	    envoy_ax_pkt_free(ax_pkt);
	    return(0);
	    }
	ax_pkt->data.reg_data.range    = range_subid;
	ax_pkt->data.reg_data.bound    = upper_bound;
	if (build_object_id(obj->num_components, obj->component_list,
			    &ax_pkt->data.reg_data.region)) {
	    *err = ENVOY_AX_ALLOCATION_FAILURE;
	    envoy_ax_pkt_free(ax_pkt);
	    return(0);
	    }
	if (flags & ENVOY_AX_BIT_NDC) {
	    EBufferPreLoad(context_dynamic, &ax_pkt->context,
			   context, context_len);
	    }
	break;

    case ENVOY_AX_PING:
	if (flags & ENVOY_AX_BIT_NDC) {
	    EBufferPreLoad(context_dynamic, &ax_pkt->context,
			   context, context_len);
	    }
	break;

    case ENVOY_AX_ADD_AC:
	if (build_object_id(obj->num_components, obj->component_list,
			    &ax_pkt->data.open_data.sub_id)) {
	    *err = ENVOY_AX_ALLOCATION_FAILURE;
	    envoy_ax_pkt_free(ax_pkt);
	    return(0);
	    }
	EBufferPreLoad(descr_dynamic, &ax_pkt->data.open_data.descr,
		       descr, descr_len);
	if (flags & ENVOY_AX_BIT_NDC) {
	    EBufferPreLoad(context_dynamic, &ax_pkt->context,
			   context, context_len);
	    }
	break;

    case ENVOY_AX_REMOVE_AC:
	if (build_object_id(obj->num_components, obj->component_list,
			    &ax_pkt->data.open_data.sub_id)) {
	    *err = ENVOY_AX_ALLOCATION_FAILURE;
	    envoy_ax_pkt_free(ax_pkt);
	    return(0);
	    }
	if (flags & ENVOY_AX_BIT_NDC) {
	    EBufferPreLoad(context_dynamic, &ax_pkt->context,
			   context, context_len);
	    }
	break;
    }
return(ax_pkt);
}


/*******************************************************************************
*
* envoy_ax_pkt_create_open - create an encoded AgentX 'OPEN' packet
* SYNOPSIS
*
* \cs
* int envoy_ax_pkt_create_open
*     ( 
*     EBUFFER_T *  ebuffp, 
*     bits8_t      version, 
*     bits8_t      flags, 
*    bits32_t     packet_id, 
*     bits8_t      time-out, 
*     bits32_t     descr_len, 
*     bits8_t   *  descr, 
*     OBJ_ID_T  *  obj
*     )
* \ce
*
* DESCRIPTION
*
* This routine creates an encoded AgentX 'OPEN' packet and places the encoded 
* packet in <ebuffp>. Since this routine does not create a lasting AgentX 
* packet structure, it does not keep a pointer to <descr>.
*
* PARAMETERS
* \is
* \i <*ebuffp>
* Point to an <ebuffp> structure that will be filled with the encoded packet. 
* The <ebuffp> may be a start pointer to an offset in this <ebuffp> or a next 
* pointer to another <ebuffp>. If no space is provided in the <ebuffp>, it is 
* the responsibility of the caller to free this space. You can use 
* SNMP_memory_alloc(), SNMP_memory_free() to allocate space in an <ebuffp>.
* \i <version>
* Specify the AgentX version number. At this release, the only supported 
* version is 'ENVOY_AX_VERSION_1'.
* \i <flags>
* Specify the bits for the flag word of the packet header. This routine 
* supports the following flag:
* \is
* \i 'ENVOY_AX_BIT_BYTE_ORDER'
* Select network-byte order for encoding or decoding.
* \ie
* \i <packet_id>
* Specify a number that allows the requester to match responses to requests.
* \i <timeout>