|
DataMuseum.dkPresents historical artifacts from the history of: DKUUG/EUUG Conference tapes |
This is an automatic "excavation" of a thematic subset of
See our Wiki for more about DKUUG/EUUG Conference tapes Excavated with: AutoArchaeologist - Free & Open Source Software. |
top - metrics - downloadIndex: T m
Length: 25033 (0x61c9)
Types: TextFile
Names: »msap.3n«
└─⟦2d1937cfd⟧ Bits:30007241 EUUGD22: P.P 5.0
└─⟦e83f91978⟧ »EurOpenD22/isode/osimis-2.0.tar.Z«
└─⟦d846658bd⟧
└─⟦this⟧ »osimis/msap/msap.3n«
#######################################################################
# #
# Copyright (c) 1988 University College London #
# All rights reserved. #
# #
# Redistribution and use in source and binary forms are permitted #
# provided that the above copyright notice and this paragraph are #
# duplicated in all such forms and that any documentation, #
# advertising materials, and other materials related to such #
# distribution and use, acknowledge that the software was developed #
# by the Department of Computer Science, University College London. #
# The name of the University may not be used to #
# endorse or promote products derived from this software without #
# specific prior written permission. #
# THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR #
# IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED #
# WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE. #
# #
#######################################################################
Common Management Information Service Primitives - Embryo manual page,
to be read in conjunction with the header files `msap.h' and `mpep.h'.
Programs that use the CMIS interface should be linked with the CMIS,
Directory and ISODE libraries (libmsap.a, libdsap.a and libisode.a).
NAME
M_InitialiseReq - Open a management connection
SYNOPSIS
#include <isode/rosap.h>
#include <isode/msap.h>
int M_InitialiseReq (CallingTitle, CallingAddr, CalledTitle, CalledAddr,
context, protvrsn, fununits, access, info, mc, mi)
AEI CallingTitle, CalledTitle;
struct PSAPaddr * CallingAddr, * CalledAddr;
char * context;
int protvrsn, fununits;
External * access, * info;
struct MSAPconnect * mc;
struct MSAPindication * mi;
DESCRIPTION
Attempts to open a management level connection to the entity
CalledTitle at address CalledAddr. The Calling parameters
may be left NULLAEI and NULLPA respectively. context is the
application level context for the connection (i.e. "management").
protvrsn is an integer whose bits indicate the CMIP versions
supported, at present it should be 1 for version1 (bit 0 set).
fununits is an integer whose bits are intended to indicate the
capabilities of the caller. It is passed unaltered to the called
entity.
access is an application defined external parameter, a pointer
to a struct type_UNIV_EXTERNAL as in <isode/pepy/UNIV-types.h>
(typedef'd as External). It may be created using the
routine external_create () (see manual entry) and free'd using
external_free (). NULLACCESS may be used if there are no
access control requirements.
info is user information to be sent with the association request.
It is of type External * as access. NULLEXTERN (the same as
NULLACCESS) may be used if no information is to be sent.
The mc structure is updated if the connection establishment is
successful (an M-ASSOCIATE.CONFIRMATION event) to contain information
about the connection, including an integer descriptor to be
used in all references to this connection.
The mi structure is updated iff the connection fails and contains
the reason - in particular mi->mi_abort.ma_data is a human readable
reason for the failure.
DIAGNOSTICS
OK is returned if the connection establishment is successful,
NOTOK otherwise.
SEE ALSO
Isode User's Manual Section 2.2 Vol. 1, IS 9596 (CMIP/S),
external_build ().
NAME
M_Init - Initialise a management responder
SYNOPSIS
#include <isode/rosap.h>
#include <isode/msap.h>
int M_Init (vecp, vec, ms, mi)
int vecp;
char ** vec;
struct MSAPindication * mi;
struct MSAPstart * ms;
DESCRIPTION
This routine must be called by a responder as soon as it
is invoked, passing its argv and argc as the first two
arguments. If the call is successful then the return is
equivalent to an M-ASSOCIATE.INDICATION event.
The association information is contained in the MSAPstart
structure, including the association descriptor.
DIAGNOSTICS
NOTOK is returned upon error, the reason being in the
MSAPindication structure, as above. OK otherwise.
SEE ALSO
Isode User's Manual Section 2.2 Vol. 1, IS 9596 (CMIP/S).
NAME
M_InitialiseResp - Respond to a connection request
SYNOPSIS
#include <isode/rosap.h>
#include <isode/msap.h>
int M_InitialiseResp (ms, status, resptitle, respaddr,
context, protvrsn, fununits, access, info, mi)
struct MSAPstart * ms;
int status;
AEI resptitle;
struct PSAPaddr * respaddr;
OID context;
int protvrsn, fununits;
External * access, * info;
struct MSAPindication * mi;
DESCRIPTION
ms is the structure filled by the M_Init routine.
Set status to ACS_ACCEPT to accept the connection request,
otherwise use ACS_TRANSIENT or ACS_PERMANENT for a transient
or permanent rejection respectively.
resptitle and respaddr may be set to NULLAEI and NULLPA.
context may be set to NULLOID if the requester's
application context is acceptable.
protvrsn, fununits, access, and info are as in M_InitialiseReq.
DIAGNOSTICS
OK is returned on success, otherwise NOTOK is returned
and mi->mi_abort is updated.
SEE ALSO
Isode User's Manual Section 2.2 Vol. 1, IS 9596 (CMIP/S),
external_build ().
NAME
M_TerminateReq - orderly connection release request
SYNOPSIS
#include <isode/rosap.h>
#include <isode/msap.h>
int M_TerminateReq (msd, reason, info, mi)
int msd, reason;
PE info;
struct MSAPindication * mi;
DESCRIPTION
Requests the release of a management association referred
to by the descriptor msd. The reason should be one of
ACF_NORMAL, ACF_URGENT, ACF_UNDEFINED.
info is user information to be sent with the association release
request. It is passed transparently to the service user's peer.
DIAGNOSTICS
OK is returned if the connection has been released, otherwise
NOTOK is returned and mi->mi_abort is updated.
SEE ALSO
Isode User's Manual Section 2.2 Vol. 1, IS 9596 (CMIP/S).
NAME
M_TerminateResp - Respond to a Terminate request
SYNOPSIS
#include <isode/rosap.h>
#include <isode/msap.h>
int M_TerminateResp (msd, status, reason, info, mi)
int msd, status, reason;
PE info;
struct MSAPindication * mi;
DESCRIPTION
msd is the descriptor of an association on which
a terminate request has been received.
status should be either ACS_ACCEPT if the association is to be
released, or ACS_REJECT otherwise.
reason should be one of ACR_NORMAL, ACR_NOTFINISHED or
ACR_UNDEFINED.
info is user information to be sent with the association release
response. It is passed transparently to the service user's peer.
DIAGNOSTICS
OK is returned upon success and the association is released,
otherwise NOTOK is returned and mi->mi_abort is updated.
SEE ALSO
Isode User's Manual Section 2.2 Vol. 1, IS 9596 (CMIP/S).
NAME
M_AbortReq - Request abrupt release of connection
SYNOPSIS
#include <isode/rosap.h>
#include <isode/msap.h>
int M_AbortReq (msd, info, mi)
int msd;
External * info;
struct MSAPindication * mi;
DESCRIPTION
Request the abrupt release of the association referenced by msd.
info is user information to be sent with the abort request
(as in M_InitialiseReq).
DIAGNOSTICS
OK is returned upon success and the association is immediately
released with any data queued possibly lost,
otherwise NOTOK is returned and mi->mi_abort is updated.
SEE ALSO
Isode User's Manual Section 2.2 Vol. 1, IS 9596 (CMIP/S),
external_build ().
NAME
Operations and Results - Event Report, Get, Set, Action,
Create, Delete, Linked Reply
SYNOPSIS
#include <isode/rosap.h>
#include <isode/msap.h>
int M_EventRep (msd, invoke, obj_class, obj_inst, type, time,
info, mi)
int msd, invoke;
MID obj_class, type;
MN obj_inst;
char * time;
PE info;
struct MSAPindication * mi;
int M_EventReC (msd, invoke, obj_class, obj_inst,
type, time, info, mi)
/* arguments as above */
int M_EventRepRes (msd, invoke, obj_class, obj_inst, time, reply,
error, err_info, mi)
int msd, invoke;
MID obj_class;
MN obj_inst;
char * time;
CMISparam * reply;
CMISerrors error;
CMISerrparam * err_info;
struct MSAPindication * mi;
int M_Get (msd, invoke, obj_class, obj_inst, scope, filter,
access, sync, nattrs, attrs, mi)
int msd, invoke;
MID obj_class;
MN obj_inst;
Scope * scope;
CMISfilter * filter;
External * access;
CMISsync sync;
int nattrs;
MID attrs;
struct MSAPindication * mi;
int M_GetRes (msd, invoke, linked, obj_class, obj_inst, time,
nattrs, attrs, error, err_info, mi)
int msd, invoke, linked;
MID obj_class;
MN obj_inst;
char * time;
int nattrs;
CMISparam * attrs;
CMISerrors error;
CMISerrparam * err_info;
struct MSAPindication * mi;
int M_Set (msd, invoke, obj_class, obj_inst, scope, filter,
access, sync, nattrs, attrs, mi)
int msd, invoke;
MID obj_class;
MN obj_inst;
Scope * scope;
CMISfilter * filter;
External * access;
CMISsync sync;
int nattrs;
CMISparam * attrs;
struct MSAPindication * mi;
int M_SetC (msd, invoke, obj_class, obj_inst, scope, filter,
access, sync, nattrs, attrs, mi)
/* arguments as above */
int M_SetRes (msd, invoke, linked, obj_class, obj_inst, time,
nattrs, attrs, error, err_info, mi)
int msd, invoke, linked;
MID obj_class;
MN obj_inst;
char * time;
int nattrs;
CMISparam * attrs;
CMISerrors error;
CMISerrparam * err_info;
struct MSAPindication * mi;
int M_Action (msd, invoke, obj_class, obj_inst, scope, filter,
access, sync, type, info, mi)
int msd, invoke;
MID obj_class;
MN obj_inst;
Scope * scope;
CMISfilter * filter;
External * access;
CMISsync sync;
MID type;
PE info;
struct MSAPindication * mi;
int M_ActionC (msd, invoke, obj_class, obj_inst, scope, filter,
access, sync, type, info, mi)
int M_ActionRes (msd, invoke, linked, obj_class, obj_inst,
time, reply, error, err_info, mi)
int msd, invoke, linked;
MID obj_class;
MN obj_inst;
char * time;
CMISparam * reply;
CMISerrors error;
CMISerrparam * err_info;
struct MSAPindication * mi;
int M_Create (msd, invoke, obj_class, obj_inst, inst_type, ref_inst,
access, nattrs, attrs, mi)
int msd, invoke;
MID obj_class;
MN obj_inst, ref_inst;
int inst_type;
External * access;
int nattrs;
CMISparam * attrs;
struct MSAPindication * mi;
int M_CreateRes (msd, invoke, obj_class, obj_inst, time,
nattrs, attrs, error, err_info, mi)
int msd, invoke;
MID obj_class;
MN obj_inst;
char * time;
int nattrs;
CMISparam * attrs;
CMISerrors error;
CMISerrparam * err_info;
struct MSAPindication * mi;
int M_Delete (msd, invoke, obj_class, obj_inst, scope, filter,
access, sync, mi)
int msd, invoke;
MID obj_class;
MN obj_inst;
Scope * scope;
CMISfilter * filter;
External * access;
CMISsync sync;
struct MSAPindication * mi;
int M_DeleteRes (msd, invoke, linked, obj_class, obj_inst, time,
error, err_info, mi)
int msd, invoke, linked;
MID obj_class;
MN obj_inst;
char * time;
CMISerrors error;
CMISerrparam * err_info;
struct MSAPindication * mi;
DESCRIPTION
msd is the appropriate association descriptor.
invoke is the invoke id for the operation or result.
linked is the linked identifier for linked replies.
It should have the same value as that of the request invoke id
for all the replies but the last one (end of linked replies).
NOLINKED (or NULL) may be used for the last linked reply
or a single one.
mi is a pointer to a MSAPindication structure which
is updated only if the call fails.
The remaining arguments are the parameters for the remote
operation request or reply. If a parameter is specified as
optional, then the appropriate NULL<x> may be used (e.g. NULLPE).
The call returns as soon as the operation is queued, it does not
wait for the result (if any).
M_WaitReq must be used to wait for a reply.
obj_class is of type MID, a pointer to a MIDent structure
which contains either an OID or an integer (global or local id).
NULLMID may be used if this argument is optional. In the case
where a MIDent structure exists instead of a pointer to it
(i.e. in the CMISerrparam structure), a null effect may be achieved
by setting mid_type to MID_GLOBAL and mid_global to NULLOID.
obj_inst is of type MN, a pointer to a MName structure
that contains either a distinguished name or a character string
(a 'non-specific' name). For the usage of routines that
manipulate distinguished names you may consult the ISODE manual,
Volume 5 Section 17 (Programming the Directory).
NULLMN may be used if this argument is optional. In the case
where a MName structure exists instead of a pointer to it
(i.e. in the CMISerrparam structure), a null effect may be achieved
by setting mn_type to MN_DN and mn_dn to NULLDN.
scope and sync apply to operations that may be performed on
multiple objects and may result in linked replies, namely M_Get,
M_Set(C), M_Action(C) and M_Delete.
scope->sc_type may take one of the values Sc_BaseObject,
Sc_FirstLevel, Sc_WholeSubtree, Sc_IndividualLevel or
Sc_BaseToNthLevel. If any of the last two is selected,
sc->sc_level should indicate the selected level.
NULLSCOPE may be used if scoping is not required.
sync may take one of the values s_bestEffort or s_atomic.
NULLSYNC (effectively s_bestEffort) may be used if
there are no synchronisation requirements.
access is an application defined external parameter, a pointer
to a struct type_UNIV_EXTERNAL as in <isode/pepy/UNIV-types.h>
(typedef'd as External). It may be created using the
routine external_create () (see manual entry) and free'd using
external_free (). NULLACCESS may be used if there are no
access control requirements.
filter is the CMIS Filter to be applied to the scoped managed
object(s). Consult <isode/mpep.h> and IS 9596 (CMIP/S).
NULLFILTER may be used if filtering is no required.
attrs in M_Get points to an array of MIDent structures
and nattrs is the number of elements in that array
(number of attribute identifiers).
NULLMID and 0 should be used respectively if all attributes
are to be selected.
attrs in M_GetRes, M_Set(C), M_SetRes, M_Create and M_CreateRes
points to an array of CMISparam structures and nattrs is the
number of elements in that array (number of attributes).
A CMISparam structure contains an identifier (mp_id - a MIDent
struct), a value (mp_val - a PE) and either a modify operator
(mp_modify) or an error code (mp_error).
NULLMPARM and 0 should be used respectively if no attribute
information is to be passed to the peer entity.
The information in CMISparam for the above CMIS primitives should be:
In M_GetRes, if a requested attribute value is to be returned,
mp_id should be set to the attribute id and mp_val should contain
the attribute value. If one or more attribute values cannot be
returned, mp_id should be set to the attribute id and mp_error
should contain the error code (m_accessDenied or m_noSuchAttribute).
error should be then set to m_getListError.
In M_Set(C), mp_id is the attribute id of the attribute to be
set, mp_val is its value and mp_modify is one of m_replace,
m_addValue, m_removeValue, m_setToDefault
(in the latter case the attribute value is not required).
In M_SetRes, if the set operation on an attribute was successful,
mp_id should be set to the attribute id and mp_id to the attribute
value after the set operation. If one or more set operations on
attributes could not be performed, mp_id should be set to the
attribute id, mp_val should contain the supplied value and
mp_error should contain the error code (one of m_accessDenied,
m_noSuchAttribute, m_invalidAttributeValue, m_invalidOperation,
m_invalidOperator). error should then be set to m_setListError.
In M_Create, mp_id and mp_val are the attribute id and value
of the attributes to be initialised.
In M_CreateRes, mp_id and mp_val are the attribute id and value
of the attributes that have been initialised.
inst_type in M_Create specifies the type of the object instance
and should be either CA_OBJECT_INST or CA_PARENT_INST for object
and parent instance respectively.
type in M_EventRep/M_Action is the event/action type (a MID)
and info is the event/action information (a PE).
NULLPE may be used for no event report/action information.
reply in M_EventRepRes/M_ActionRes is the event report/action reply.
reply->mp_id should contain the event report/action type id and
reply->mp_val should contain the event report/action information.
NULLMPARM may be used for a null reply.
error contains the error code if an error has occurred while
processing an operation request. Any error information should be
contained in an instance of a CMISerrparam structure, pointed
by err_info. m_getListError and m_setListError are treated
as results rather than errors (partial success).
In the case of success, error may be set to m_noError or NULLMERROR
and err_info may be set to NULLMERRPARM.
A CMISerrparam structure contains the following fields:
object class (me_class - a MIDent struct), object
instance (me_inst - a MName struct), time (me_time),
scope (me_scope - a Scope struct), synchronisation (me_sync),
an identifier (me_id - a MIDent struct), a value (me_val -
a PE) and either a modify operator (me_modify) or an
error code (me_error).
The error information that should be contained in that structure
is specified below for each error code.
m_noSuchObjectClass object class (me_class)
m_noSuchObjectInstance
m_invalidObjectInstance
m_duplicateManagedObjectInstance
m_noSuchReferenceObject object instance (me_inst)
m_accessDenied none
m_syncNotSupported synchronisation (me_sync)
m_invalidFilter filter (me_filter)
m_noSuchAttribute
m_missingAttributeValue attribute id (me_id)
m_invalidAttributeValue attribute id (me_id)
attribute val (me_val)
m_noSuchAction object class (me_class)
action type id (me_id)
m_processingFailure object class (me_class)
object instance (me_inst) optional
specific error info (me_val)
m_noSuchEventType object class (me_class)
event type id (me_id)
m_noSuchArgument object class (me_class) optional
action/event type id (me_id)
m_invalidArgumentValue action/event type id (me_id)
action/event info (me_val) optional
m_invalidScope scope (me_scope)
m_classInstanceConflict object class (me_class)
object instance (me_inst)
m_complexityLimitation scope (me_scope) optional
filter (me_filter) optional
synchronisation (me_sync) optional
In the case of a delete linked reply error other than
m_processingFailure (can only be m_accessDenied), the error
information should be the object class (me_class), object
instance (me_inst) and current time (me_time), all optional.
In the case of an action linked reply error other than
m_processingFailure (one of m_accessDenied, m_noSuchAction,
m_noSuchArgument, m_invalidArgumentValue), the error
information should be the one defined above for the
appropriate error code plus the object class (me_class),
object instance (me_inst) and current time (me_time),
the last three optional.
DIAGNOSTICS
NOTOK is returned on failure, mi->mi_preject contains
the reason (mr_data is a readable string). The most likely
error is "Bad Arguments" caused by a failure in the
pepy generated encoder.
SEE ALSO
Isode User's Manual Section 3 Vol. 1 (Remote Operations),
Isode User's Manual Section 17 Vol. 5 (Programming the Directory),
IS 9596 (CMIP/S), X.410 (ROS),
external_build ().
NAME
M_WaitReq - Wait for data on a connection
SYNOPSIS
#include <isode/rosap.h>
#include <isode/msap.h>
int M_WaitReq (msd, secs, mi)
int msd, secs;
struct MSAPindication * mi;
DESCRIPTION
Allows the service user to wait for up to secs seconds
for an event to occur on the association referred to by msd.
If secs is NOTOK the call blocks indefinitely, whereas
if secs is OK the call returns immediately (e.g. a poll).
The MSAPindication structure is ALWAYS updated:
if an operation request or reply is received, the mi->mi_type
field indicates its type and the remainder of the structure
contains the invoke id and the decoded arguments, as passed
to the operation request or reply routine.
If the mi_type field contains MI_TERM then a terminate
request has been received. The peer supplied reason is
contained in the MSAPindication structure.
DIAGNOSTICS
OK is returned on success, otherwise NOTOK is returned
and the reason for the failure is contained in mi->mi_preject.
SEE ALSO
Isode User's Manual Section 3.3.4.
NAME
xfree - Free management structures
SYNOPSIS
#include <isode/rosap.h>
#include <isode/msap.h>
mcfree (mc)
struct MSAPconnect * mc;
msfree (ms)
struct MSAPstart * ms;
mafree (ma)
struct MSAPabort * ma;
mifree (ms)
struct MSAPindication * mi;
DESCRIPTION
These routines free any data that may have been
allocated to the pointed structure by the management
routines. They do not free the structures themselves.
DIAGNOSTICS
None.
SEE ALSO
Isode User's Manual Section 3.
NAME
mfilter_free - Free CMIS filter
SYNOPSIS
#include <isode/rosap.h>
#include <isode/msap.h>
mfilter_free (filter)
CMISfilter * filter;
DESCRIPTION
It frees the structures that constitute a CMIS filter
and the data contained there in.
DIAGNOSTICS
None.
SEE ALSO
IS 9596 (CMIP/S).
NAME
external_build - Build an External (type_UNIV_EXTERNAL) structure
SYNOPSIS
#include <isode/rosap.h>
#include <isode/msap.h>
External * external_create (type, ctx, pe, oct_aligned)
int type;
char * ctx;
PE pe;
struct qbuf * oct_aligned;
DESCRIPTION
It builds an External structure containing its arguments
and returns a pointer to it. An External structure is the same
as the struct type_UNIV_EXTERNAL in <isode/pepy/UNIV-types.h>
and reprsents the ASN.1 type EXTERNAL.
type should be one of EXTERN_ASN1_TYPE, EXTERN_ARBITRARY and
EXTERN_OCTET_ALIGNED. In the case of the first two, the actual
external parameter is a pe while in the case of EXTERN_OCTET_ALIGNED
the parameter is a struct qbuf * (oct_aligned).
ctx is the ASN.1 module of the parameter in string form
e.g. "x.y.v.z".
The storage allocated for the structure may be free'd using
external_free ().
DIAGNOSTICS
An External * is returned upon success, (External *) NULL otherwise.
SEE ALSO
IS 9596 (CMIP/S).