.\"
.\" $Id: smi_node.3.in,v 1.3 1999/06/16 15:04:16 strauss Exp $
.\"
.TH smi_node 3  "June 16, 1999" "IBR" "SMI Management Information Library"
.SH NAME
smiGetNode, smiGetFirstNode, smiGetNextNode, smiFreeNode \- SMI type
information routines
.SH SYNOPSIS
.nf
.B #include <smi.h>
.RS
.RE
.sp
.BI "SmiNode *smiGetNode(char *" module ", char *" name );
.RE
.sp
.BI "SmiNode *smiGetNodeByOID(unsigned int" oidlen ", Subid" oid[] );
.RE
.sp
.BI "SmiNode *smiGetFirstNode(char *" module ", SmiNodekind " kinds );
.RE
.sp
.BI "SmiNode *smiGetNextNode(SmiNode *" smiNodePtr ", SmiNodekind " kinds );
.RE
.sp
.BI "SmiNode *smiGetParentNode(SmiNode *" smiNodePtr );
.RE
.sp
.BI "SmiNode *smiGetFirstChildNode(SmiNode *" smiNodePtr );
.RE
.sp
.BI "SmiNode *smiGetNextChildNode(SmiNode *" smiNodePtr );
.RE
.sp
.BI "SmiNode *smiGetFirstIndexNode(SmiNode *" smiRowNodePtr );
.RE
.sp
.BI "SmiNode *smiGetNextIndexNode(SmiNode *" smiRowNodePtr ", SmiNode *" smiIndexNodePtr );
.RE
.sp
.BI "SmiNode *smiGetFirstMemberNode(SmiNode *" smiGroupNodePtr );
.RE
.sp
.BI "SmiNode *smiGetNextMemberNode(SmiNode *" smiGroupNodePtr ", SmiNode *" smiMemberNodePtr );
.RE
.sp
.BI "SmiNode *smiGetFirstObjectNode(SmiNode *" smiNotificationNodePtr );
.RE
.sp
.BI "SmiNode *smiGetNextObjectNode(SmiNode *" smiNotificationNodePtr ", SmiNode *" smiObjectNodePtr );
.RE
.sp
.BI "SmiNode *smiGetFirstMandatoryNode(SmiNode *" smiComplianceNodePtr );
.RE
.sp
.BI "SmiNode *smiGetNextMandatoryNode(SmiNode *" smiComplianceNodePtr ", SmiNode *" smiMandatoryNodePtr );
.RE
.sp
.BI "void smiFreeNode(SmiNode *" smiNodePtr );
.RE
.sp
.BI "SmiOption *smiGetFirstOption(SmiNode *" smiComplianceNodePtr );
.RE
.sp
.BI "SmiOption *smiGetNextOption(SmiNode *" smiComplianceNodePtr ", SmiOption *" smiOptionPtr );
.RE
.sp
.BI "void smiFreeOption(SmiOption *" smiOptionPtr );
.RE
.sp
.BI "SmiRefinement *smiGetFirstRefinement(SmiNode *" smiComplianceNodePtr );
.RE
.sp
.BI "SmiRefinement *smiGetNextRefinement(SmiNode *" smiComplianceNodePtr ", SmiRefinement *" smiRefinementPtr );
.RE
.sp
.BI "void smiFreeRefinement(SmiRefinement *" smiRefinementPtr );
.RE

typedef struct SmiNode {
    SmiIdentifier       module;
    SmiIdentifier       name;
    SmiObjectIdentifier oid;        /* dotted string */
    SmiIdentifier       typename;
    SmiIdentifier       typemodule;
    SmiIndexkind        indexkind;    
    int                 implied;    /* implied index length? */
    int                 create;     /* creatable table rows? */
    SmiIdentifier       relatedmodule;
    SmiIdentifier       relatedname;
    SmiDecl             decl;
    SmiBasetype         basetype;
    SmiAccess           access;
    SmiStatus           status;
    char                *format;
    SmiValue            *valuePtr;
    char                *units;
    char                *description;
    char                *reference;
} SmiNode;

typedef struct SmiOption {
    SmiIdentifier       module;
    SmiIdentifier       name;
    SmiIdentifier       compliancemodule;
    SmiIdentifier       compliancename;
    char                *description;
} SmiOption;
 
typedef struct SmiRefinement {
    SmiIdentifier       module;
    SmiIdentifier       name;
    SmiIdentifier       compliancemodule;
    SmiIdentifier       compliancename;
    SmiIdentifier       typemodule;
    SmiIdentifier       typename;
    SmiIdentifier       writetypemodule;
    SmiIdentifier       writetypename;
    SmiAccess           access;
    char                *description;
} SmiRefinement;


.fi
.SH DESCRIPTION
These functions retrieve information on any node definition in the
object identifier tree, these are ASN.1 object identifier assignments,
MODULE-IDENTITYs, OBJECT-IDENTITYs, OBJECT-TYPEs, NOTIFICATION-TYPEs,
TRAP-TYPEs, OBJECT-GROUPs, NOTIFICATION-GROUPs, MODULE-COMPLIANCEs,
and AGENT-CAPABILITYs in SMIv1/v2 and module, node, scalar, table,
row, column, notification, group, and compliance statements in SMIng.
.PP
The \fBsmiGetNode()\fP function retrieves a \fBstruct SmiNode\fP that
represents a node of any kind. Either \fIname\fP must be the fully
qualified identifier leaving \fImodule\fP NULL, or the name is split into
the module \fImodule\fP and identifier \fIname\fP. The identifier part
may also be given as a numerical OID value. In this case the \fBSmiNode\fP
that matches the longest \fIname\fP prefix will be returned. Elements not
available or not present in the definition contain NULL. See
\fBsmi.h\fP for the structure of contained elements.
.PP
The \fBsmiGetNodeByOID()\fP function retrieves a \fBstruct SmiNode\fP that
matches the longest prefix of the node that is specified by the
object identifier \fIoid[]\fP with the length \fIoidlen\fP.
Elements not available or not present in the definition contain NULL. See
\fBsmi.h\fP for the structure of contained elements.
.PP
The \fBsmiGetFirstNode()\fP and \fBsmiGetNextNode()\fP functions are
used to iteratively retrieve \fBstruct SmiNode\fPs.
\fBsmiGetFirstNode()\fP returns the first node
defined in module \fImodule\fP
that is of any kind specified in the \fIkinds\fP bitset
with respect to an object identifier tree in
pre-order (thus not necessarily the first defined in the MIB module).
Subsequent calls to \fBsmiGetNextNode()\fP release \fIsmiNodePtr\fP and
return the next node of an appropriate kind out of \fIkinds\fP. If there are no
more node definitions in the module NULL is returned.
.PP
Similarly, the \fBsmiGetFirstChildNode()\fP and \fBsmiGetNextChildNode()\fP
functions are used to iteratively retrieve \fBstruct SmiNode\fPs that
represent the immediate child nodes of that one specified
by \fIsmiNodePtr\fP to the \fBsmiGetFirstChildNode()\fP call.
.PP
Similarly, the \fBsmiGetFirstIndexNode()\fP and \fBsmiGetNextIndexNode()\fP
functions are used to iteratively retrieve \fBstruct SmiNode\fPs that
represent the index nodes of the table row specified by \fIsmiRowNodePtr\fP.
.PP
Similarly, the \fBsmiGetFirstMemberNode()\fP and \fBsmiGetNextMemberNode()\fP
functions are used to iteratively retrieve \fBstruct SmiNode\fPs that
represent the member nodes of the (object or notification) group
specified by \fIsmiGroupNodePtr\fP.
.PP
Similarly, the \fBsmiGetFirstObjectNode()\fP and \fBsmiGetNextObjectNode()\fP
functions are used to iteratively retrieve \fBstruct SmiNode\fPs that
represent the object nodes of the notification
specified by \fIsmiNotificationNodePtr\fP.
.PP
Similarly, the \fBsmiGetFirstMandatoryNode()\fP
and \fBsmiGetNextMandatoryNode()\fP
functions are used to iteratively retrieve \fBstruct SmiNode\fPs that
represent the mandatory (object or notification) groups of the compliance
statement specified by \fIsmiComplianceNodePtr\fP.
.PP
Similarly, the \fBsmiGetFirstOption()\fP
and \fBsmiGetNextOption()\fP
functions are used to iteratively retrieve \fBstruct SmiOption\fPs that
represent the optional (object or notification) groups of the compliance
statement specified by \fIsmiComplianceNodePtr\fP.
.PP
Similarly, the \fBsmiGetFirstRefinement()\fP
and \fBsmiGetNextRefinement()\fP
functions are used to iteratively retrieve \fBstruct SmiRefinement\fPs that
represent the refined objects of the compliance
statement specified by \fIsmiComplianceNodePtr\fP.
.PP
The \fBsmiFreeNode()\fP function should be called when a retrieved
\fBstruct SmiNode\fP is no longer needed to release its memory.
.PP
Similarly, the \fBsmiFreeOption()\fP function should be called when a retrieved
\fBstruct SmiOption\fP is no longer needed to release its memory.
.PP
Similarly, the \fBsmiFreeRefinement()\fP function should be called when a
retrieved \fBstruct SmiRefinement\fP is no longer needed to release its memory.
.SH "RETURN VALUES"
The retrieval functions return the requested \fBstruct smiNode\fP,
\fBstruct smiOption\fP, or \fBstruct smiRefinement\fP,
on success, or NULL on error. Structures should be released after use
by calling \fBsmiFreeNode()\fP, \fBsmiFreeOption()\fP,
or \fBsmiFreeRefinement()\fP, respectively, which are a void functions.
.SH "FILES"
.nf
/usr/local/include/smi.h    SMI library header file
.fi
.SH "SEE ALSO"
.BR libsmi "(3), "
.BR smi.h
.SH "AUTHOR"
(C) 1999 Frank Strauss, TU Braunschweig, Germany <strauss@ibr.cs.tu-bs.de>
.br