SEDRIS Transmittal Access C++ API

    seWorkspace wksp;
    seTransmittal xmtal;

    // create a transmittal
    wksp.createTransmittal(fileName, xmtal);
    ... create Transmittal Root object as needed
    xmtal.setRoot(rootObj);
    ... add top level objects as needed
    ... add a hierarchy of objects as needed
    xmtal.close();

    // open the transmittal
    wksp.openTransmittalByFile(fileName, xmtal);
    xmtal.getRootObject(rootObj);
        ... process objects

Constructor & Destructor Documentation

sedris::seTransmittal::seTransmittal ( const seTransmittal & other ) [inline]

Copy constructor, same as cloneTo().

See also:: cloneTo()

virtual sedris::seTransmittal::~seTransmittal ( ) [inline, virtual]

Destructor, releases the transmittal handle.

Warning:: The transmittal is NOT automatically closed. This is to allow to continue work on a transmittal even if a handle to it is not currently available (but you can retrieve it from an seObject handle or from the seWorkspace handle). However, the transmittal IS closed when the workspace handle goes out of scope.

See also:: seWorkspace::~seWorkspace, seWorkspace::close()

Member Function Documentation

virtual void sedris::seTransmittal::cloneTo ( seTransmittal & other ) const [virtual]

Clones this instance handle into another transmittal handle. Used to make another seTransmittal refer to the same transmittal this instance refers to.

Parameters:

other

in: transmittal to be cloned to

virtual void sedris::seTransmittal::close ( ) [virtual]

Close the transmittal. Closing a transmittal forces the writing of all opened and edited objects. You do not need to call close() explicitly if you intend the transmittal to be closed when the workspace handle goes out of scope. So for example, this code is perfectly legal since the transmittal is closed when the variable "wksp" goes out of scope:

            {
                seWorkspace wksp;
                seTransmittal xmtal;

                wksp.openTransmittalByFile(...);
                ... work on transmittal
                ... let wksp and xmtal go out of scope
            }

However, if you intend to reopen a previously opened transmittal in the same workspace and the workspace handle is still valid (i.e. it hasn't gone out of scope or seWorkspace::close() was not called), then you will need to explicitly call the close() method to close the transmittal handle or the open call will fail (since the transmittal is still opened in the workspace). For example, the following will produce a "transmittal already opened" exception:

            {
                seWorkspace wksp;
                seTransmittal xmtal;

                wksp.createTransmittal("my_test.stf");
                ... work on transmittal

                wksp.openTransmittal("my_test.stf"); <<< EXCEPTION
            }

but the following will work OK:

            {
                seWorkspace wksp;
                seTransmittal xmtal;

                wksp.createTransmittal("my_test.stf");
                ... work on transmittal

                xmtal.close(); // explicit close of transmittal

                wksp.openTransmittal("my_test.stf"); // Now OK
            }

Note:: All opened transmittals in a workspace are automatically closed when the workspace handle goes out of scope.

Warning:: If you close a transmittal, all other seTransmittal handles referring to the same transmittal will also become closed. If you just want to release the handle to the transmittal but not really close it, you can use release() instead, or just let the handle go out of scope.

virtual void sedris::seTransmittal::createObject	(	seObject &	obj,
		SE_DRM_Class	type = SE_DRM_CLS_NULL
	)	`[virtual]`

Creates a transmittal object of a specific DRM type. The object created can only be used within the transmittal that created it. That is, you can't add objects from one transmittal into another.

You can pass seDRMBase-derived concrete DRM classes to this method, in which case you don't need to specify the DRM type since it is implicit by the class of the parameter. For example, you can do:

            seDRMAccess access;

            xmtal.createObject(access);
            ...

instead of:

            seDRMAccess access;

            xmtal.createObject(access, SE_DRM_CLS_ACCESS);
            ...

If you do pass a true seObject to this method, then you MUST provide a concrete DRM class for the type parameter or an exception will occur. For example:

            seObject troot;

            xmtal.createObject(troot, SE_DRM_CLS_TRANSMITTAL_ROOT);
            ...

See also:: seDRMBase

Parameters:

obj	in/out: a handle to store the created object
type	in (optional): the class type of DRM object to create

virtual void sedris::seTransmittal::deleteObject ( seObject & obj ) [virtual]

Deletes an object from the transmittal. Prior to calling this function, the user must have removed all relationships that obj has with other objects. If the object still has aggregates, components, or associates an exception will be thrown.

In addition, note that deleting obj from the transmittal does not automatically delete its component sub-tree. (This would not be valid for the general case, since part of obj's component sub-tree might be shared with other objects). Similarly, none of obj's associates are deleted when obj is deleted. See deleteObjectTree() for an alternative way of removing a whole sub-tree at once.

The transmittal must be editable for this operation to succeed.

Note:: Once an object is deleted from the transmittal, the object handle should be released (or left to go out of scope).

See also:: deleteObjectTree()

Parameters:

obj

in: the object to be deleted from the transmittal

virtual void sedris::seTransmittal::deleteObjectTree ( seObject & obj ) [virtual]

Deletes an object and all its descendants from the transmittal by recursively removing all its relationships. This method removes the object passed in from its parent and deletes all its component objects. Since objects can be shared with other parts of the transmittal, the behaviour is to skip deletion of shared objects (but they are still removed as components of objects in the tree).

Note:: This method will detach the object passed in from all of its parents, so you do not need to do this. For example, if you want to remove an <Image> from the transmittal you can just pass in the <Image> object without removing it from the <Image Library> (but make sure that no associations exist from other parts of the transmittal to the <Image> object, see the warnings).
If the object passed-in is being shared then no action is taken.

Warning:: This method may not be able to remove all the associations to the object or its descendants (e.g. one-way relationships), so dangling references may remain. It is the responsibility of the caller to remove one-way associations from other objects in the transmittal to objects in the tree to be deleted.
Be careful when using this method in the presence of ITR references, since the deletion could proceed across the referenced transmittals.

See also:: deleteObject()

Parameters:

obj

in: the root of the object tree to be deleted from the transmittal

virtual SE_Access_Mode sedris::seTransmittal::getAccessMode ( ) const [virtual]

virtual SE_Encoding sedris::seTransmittal::getEncoding ( ) const [virtual]

Returns the encoding type of this transmittal. Encoding identifiers are used to differentiate between storage mechanisms for SEDRIS transmittals. SEDRIS transmittals stored in STF format return the encoding type SE_ENC_STF.

virtual const char* sedris::seTransmittal::getITRReference ( unsigned int urn_index ) const [virtual]

Returns the URN for an ITR referenced transmittal by index.

See also:: getITRReferenceCount()

virtual unsigned int sedris::seTransmittal::getITRReferenceCount ( ) const [virtual]

Returns the number of ITR referenced transmittals. A transmittal may contain objects that actually reference objects in other transmittals. The reference is both by a transmittal URN and the published label for an object in that transmittal. This method returns the total number of transmittals being referenced.

Note:: A transmittal may be referenced by more than one URN (aliases), but this method does not return the unique number of references. You will need to resolve a URN and compare file names to check for actual unique references.

See also:: getITRReference(), getITRReferenceLabelCount(), getITRReferenceLabel(), seWorkspace::resolveTransmittalURN()

virtual const char* sedris::seTransmittal::getITRReferenceLabel	(	unsigned int	urn_index,
		unsigned int	label_index
	)	const `[virtual]`

Returns the label (by label index) being used to reference an object in a particular URN-referenced transmittal (by URN index).

See also:: getITRReferenceLabelCount()

virtual unsigned int sedris::seTransmittal::getITRReferenceLabelCount ( unsigned int urn_index ) const [virtual]

Returns the number of labels being used to reference objects in a particular URN-referenced transmittal (by URN index).

Note:: Objects can be published under more than one label, hence this method does not return the unique number of references. You will need to resolve a URN, open the transmittal, and get the published objects to check for actual unique references.

Exceptions:

seException

if the URN is not being referenced.

See also:: getITRReferenceCount()

virtual void sedris::seTransmittal::getObjectFromID	(	const char *	str_obj_ID,
		seObject &	obj
	)	const `[virtual]`

Get an object in the transmittal by its identifier. Every object in a transmittal has an identifier that can be used to refer to it. If you have the identifier for an object (see seObject::getID()), you can use this method to retrieve that object directly without having to traverse the transmittal hierarchy.

See also:: seObject::getID()

Parameters:

str_obj_ID	in: the string object identifier
obj	in/out: the object matching the identifier

Exceptions:

seException

if the object could not be retrieved

virtual void sedris::seTransmittal::getPublishedObject	(	const char *	obj_label,
		seObject &	obj
	)	const `[virtual]`

Get an object in the transmittal based on its published label. An object that is published is available for reference from other transmittals using ITR. This method allows for direct access to a particular object based on the label that was used to publish it.

See also:: seObject::publish()

Parameters:

obj_label	in: the string object label
obj	in/out: a reference to the object with the given label

Exceptions:

seException

if there is no object published under the given label

virtual void sedris::seTransmittal::getPublishedObjectsIterator ( seIterator & iter ) const [virtual]

Initializes an iterator with the list of objects published by the transmittal for possible reference using ITR. You can use this method to get a hold of all the published objects in a transmittal. Sample usage:

            seIterator iter;
            seObject obj;

            xmtal.getPublishedObjectsIterator(iter);
            while (iter.getNext(obj))
            {
                unsigned int i, cnt = obj.getPublishedLabelCount();

                for (i=0; i < cnt; i++)
                {
                    cout << obj.getPublishedLabel(i) << endl;
                }
            }

Note:: The returned objects are unique objects in a transmittal. That is, if an object A is published under multiple labels, then the iterator will return object A only once.

Parameters:

iter

in/out: an iterator handle

virtual void sedris::seTransmittal::getRootObject ( seObject & obj ) const [virtual]

Get the object that has been stored as the root of the transmittal hierarchy.

Note:: Currently the root object for a transmittal should be a <Transmittal_Root> object, but the API does not currently enforce neither the setting of the root object nor the type being used.

Warning:

As currently implemented, if the root object is not set while creating a transmittal, the first object created is the default root object.

            seWorkspace wksp;
            seTransmittal xmtal;
            seDRMTransmittalRoot troot;

            try
            {
                wksp.openTransmittalByFile(...);
                xmtal.getRootObject(troot);
                ... work on transmittal
            }
            ...

See also:: setRootObject()

Parameters:

obj

in/out: the handle to store the root object

virtual const char* sedris::seTransmittal::getUniqueID ( ) const [virtual]

Returns the transmittal unique identifier. Unique identifiers are assigned to transmittals every time a transmittal is modified and saved (for example after creation or update on transmittal closing). The unique identifier returned by this method is a character string suitable for printing, comparison, or storage operations.

Unique identifiers are automatically managed by the API, so there are no methods that allow you to change or set them to specific values. You can use unique identifiers to compare two transmittals to see if they are in fact the same transmittals (for example two transmittals may have different file names but contain the same data).

            cout << "Unique identifier is " << xmtal.getUniqueID() << endl;

virtual const char* sedris::seTransmittal::getURN ( ) const [virtual]

Returns the transmittal URN associated with this transmittal.

Note:: If the transmittal does not have a URN set, the returned string may be empty.

See also:: setURN()

Returns:: URN of transmittal

virtual bool sedris::seTransmittal::isEditable ( ) const [virtual]

Returns true if this transmittal is opened and editable. A transmittal is "editable" if it is opened in create or edit mode.

See also:: getAccessMode()

virtual bool sedris::seTransmittal::isInWorkspace ( const seWorkspace & wksp ) const [virtual]

Returns true if this transmittal was opened in the passed-in workspace.

Parameters:

wksp

in: handle to workspace

Returns:: true if transmittal is in workspace

virtual bool sedris::seTransmittal::isModified ( ) const [virtual]

Returns true if this transmittal was modified (for example if objects were added or deleted).

virtual bool sedris::seTransmittal::isSameAs ( const seTransmittal & other ) const [virtual]

Returns true if the transmittal passed in is a clone of this one (i.e. both handles reference the same transmittal).

virtual seTransmittal& sedris::seTransmittal::operator= ( const seTransmittal & other ) [inline, virtual]

Copy operator, same as cloneTo().

Note:: This operator only makes one seTransmittal handle point to the same transmittal as another handle. This method is NOT used to copy an actual transmittal's data. See cloneTo() for more details.

See also:: cloneTo()

virtual void sedris::seTransmittal::release ( ) [virtual]

Releases the handle to the transmittal. Generally there is no need to call this method, since release() is called by any change of handle or when the object goes out of scope.

Note:: This method does not close the transmittal if there are other handles referring to the same transmittal.

See also:: close()

virtual void sedris::seTransmittal::setRootObject ( seObject & obj ) [virtual]

Set the root object for the transmittal hierarchy. The root object of a transmittal is the root of the DRM hierarchy stored in the transmittal. You can continue adding objects to the root object after calling this method.

Note:: If already set, this call replaces the previous root object.

Warning:: Calling this function will permanently change the root object of the transmittal. If the transmittal already has a root object, you must remove the previous root object's relationships in order to avoid orphaning objects within the transmittal.

See also:: getRootObject()

Parameters:

obj

in: the new root object for the transmittal

virtual void sedris::seTransmittal::setURN ( const char * urn ) [virtual]

Set (or modify) the URN for the transmittal. You are encouraged to always assign a URN to transmittals you create. Every transmittal should have a unique URN. The URN set by this method is stored in the transmittal file. URNs are of the form "urn:sedris:xyzcorp:xyz_data_orlando:1".

Warning:: While all transmittals should have a URN assigned to them, care should be taken when invoking this function since the API is not responsible for managing configuration and changing control for the transmittal being modified. Calling this function will PERMANENTLY change the transmittal name associated with the file containing the SEDRIS transmittal. Be sure this is the desired result BEFORE calling this function.

Note:: The URN must pass the SE_ValidTransmittalName() function.

See also:: seWorkspace::resolveTransmittalURN(), seWorkspace::openTransmittalByURN()

Parameters:

urn

in: the new URN for the transmittal


Public Member Functions
	seTransmittal ()
	Constructor.
	seTransmittal (const seTransmittal &other)
virtual	~seTransmittal ()
virtual seTransmittal &	operator= (const seTransmittal &other)
virtual bool	isValid () const
	Returns true if this transmittal handle is valid.
virtual bool	isOpened () const
	Returns true if this transmittal is opened.
virtual bool	isEditable () const
virtual bool	isModified () const
virtual const char *	getFileName () const
	Returns the file location of this transmittal.
virtual SE_Access_Mode	getAccessMode () const
	Returns the access mode used to open this transmittal.
virtual SE_Encoding	getEncoding () const
virtual void	close ()
virtual void	getRootObject (seObject &obj) const
virtual void	setRootObject (seObject &obj)
virtual void	createObject (seObject &obj, SE_DRM_Class type=SE_DRM_CLS_NULL)
virtual void	deleteObject (seObject &obj)
virtual void	deleteObjectTree (seObject &obj)
virtual void	getObjectFromID (const char *str_obj_ID, seObject &obj) const
virtual void	getPublishedObject (const char *obj_label, seObject &obj) const
virtual void	getPublishedObjectsIterator (seIterator &iter) const
virtual void	setURN (const char *urn)
virtual const char *	getURN () const
virtual unsigned int	getITRReferenceCount () const
virtual const char *	getITRReference (unsigned int urn_index) const
virtual unsigned int	getITRReferenceLabelCount (unsigned int urn_index) const
virtual const char *	getITRReferenceLabel (unsigned int urn_index, unsigned int label_index) const
virtual const char *	getUniqueID () const
virtual void	cloneTo (seTransmittal &other) const
virtual bool	isSameAs (const seTransmittal &other) const
virtual void	release ()
virtual bool	isInWorkspace (const seWorkspace &wksp) const

SEDRIS Transmittal Access C++ API	4.0.0 beta - 14 Jul 2004
Copyright © 2004 SEDRIS™	Docs by Doxygen 1.3.2

sedris::seTransmittal Class Reference

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation