Interface IdCardGetterInterface

The IdCardGetterInterface interface is used to retrieve information about a part instance (and not a geometric instance id), such as the metadata of the part, link, the list of part instance ancestors, attached document, ....

The metadata documents and general information can be retrieved by knowing the part instance to retrieve. If such a document is requested after a picking, then the given geometric instance id must be converted to a part instance id.

The IdCardGetterInterface interfaces are created through the DataSessionInterface.createIdCardGetter method.

/** 
 * Sample to illustrate the use of an IdCardGetterInterface from a `geometric instance id`.
 */
import {
    WorkingSetInterface, IdCardGetterInterface, GeometricInstanceConverterInterface,
    IdCardGetterInterfaceSignal, GeometricInstanceConverterInterfaceSignal, DataSessionInterface,
} from 'generated_files/documentation/appinfiniteapi';
// the `part instances` are retrieved by a picking for example

// the DataSessionInterface has been created previously and is connected
let lDataSession : DataSessionInterface;
// the `geometric instance id` to get information from
let lGeometricInstanceId : number;
// create a `geometric instance id` converter
const lGeometricConverter : GeometricInstanceConverterInterface = lDataSession.createGeometricInstanceConverter();
// the current Working set has been created previously
let lVisibilityContext : WorkingSetInterface;
// what to do when the conversion from picking is ready
let onPartInstanceReady : (pEvent, _pCallbackData) => void;
// what to do when the id card retrieval is over
let onIdCardReady : (pEvent, _pCallbackData) => void;

// id card getter interface creation
const lIdCardGetterInterface : IdCardGetterInterface = lDataSession.createIdCardGetter();
// connect the IDCardReady signal to the handling of the metadata of the `part instance` and its genealogy 
lIdCardGetterInterface.addEventListener(IdCardGetterInterfaceSignal.IdCardReady, onIdCardReady);

// the `geometric instance` to get
const lGeometricInstanceIds: Uint32Array = new Uint32Array(1);
lGeometricInstanceIds[0] = lGeometricInstanceId;
// connect the GeometricInstanceConverterReady signal to the id card retrieval
lGeometricConverter.addEventListener(GeometricInstanceConverterInterfaceSignal.GeometricInstanceConverterReady, onPartInstanceReady);

onPartInstanceReady = (_pEvent, _pCallbackData) : void =>
{
    // triggered when we have all the `part instances` of the given geometry
    const lPartInstanceIds : Uint32Array| undefined = lGeometricConverter.getPartInstanceIds();
    if (lPartInstanceIds && (lPartInstanceIds.length > 0))
    {
        // only get the id-card of the first `part instance` (we may do other things if multiple id-cards to retrieve)
        // onIdCardReady will be called shortly after
        lIdCardGetterInterface.retrieveIdCard(lPartInstanceIds[0], lVisibilityContext);
    }
};

// trigger the conversion
lGeometricConverter.convert(lGeometricInstanceIds, lVisibilityContext);

Copy

The list of signals the IdCardGetterInterface may trigger is available in the IdCardGetterInterfaceSignal enumeration.

The metadata retrieval procedure is triggered through the retrieveIdCard methods. The result is not available right away, but the event IdCardGetterInterfaceSignal.IdCardReady is triggered when the result of the IdCardGetterInterface is available. The result is available through the getPartInstanceInfos function.

Warning : there may be cases when the getPartInstanceInfos is not available such as when the IdCardGetterInterface is updating, i.e. when isRunning returns true, or when the IdCardGetterInterface has been cancelled, i.e. when isCancelled returns true.

An IdCardGetterInterface may be interrupted (cancelled) when the IdCardGetterInterface is updating and cancel is called. In such cases, the IdCardGetterInterfaceSignal.IdCardCancelled signal is fired, and shortly after, IdCardGetterInterfaceSignal.IdCardReady signal is fired, but getPartInstanceInfos will return undefined. Just call retrieveIdCard with another (or the same) part instance ids to trigger a new retrieval.

If you call multiple times retrieveIdCard before receiving the IdCardGetterInterfaceSignal.IdCardReady, only one IdCardGetterInterfaceSignal.IdCardReady will be sent with the content of the last call to retrieveIdCard.

The developer may process the results of an id card retrieval with the following code :

/** 
 * Sample to illustrate the use of an IdCardGetterInterface with the parsing of
 * PartInstanceInfoInterface to display some information about a part instance.
 */
import {
    WorkingSetInterface, IdCardGetterInterface, IdCardGetterInterfaceSignal,
    InfiniteEvent, PartInstanceInfoInterface, DataSessionInterface, AncestryInstanceMetadataInterface, DocumentContentInterface
} from 'generated_files/documentation/appinfiniteapi';

// the DataSessionInterface has been created previously and is connected
let lDataSession : DataSessionInterface;
// created previously
let lVisibilityContext : WorkingSetInterface;
// the `part instance id` to get
let lPartInstanceId : number;
// what to do when we have retrieved id card information ?
let onIdCardReady : (_pEvent: InfiniteEvent, _pCallbackData: Object | undefined) => void;

// create an idCardGetter
const lIdCardGetterInterface : IdCardGetterInterface = lDataSession.createIdCardGetter();
// what to do when result is ready ?
lIdCardGetterInterface.addEventListener(IdCardGetterInterfaceSignal.IdCardReady, onIdCardReady);

// onIdCardReady will be called when data is available
onIdCardReady = (_pEvent: InfiniteEvent, _pCallbackData: Object | undefined) : void =>
{
    if (lIdCardGetterInterface.getLastError() !== undefined) {
        // do nothing in case of error
        // perhaps some GUI code ?
    }
    const lPartInstanceInfos : Array<PartInstanceInfoInterface> | undefined = lIdCardGetterInterface.getPartInstanceInfos();
    if (!lPartInstanceInfos || lPartInstanceInfos.length !== 1)
    {
        // no data (isCancelled ?)
        return;
    }
    // we required only one `part instance`, as such, only one result should be retrieved
    // iterate over the instantiation chain, but take the first chain since one `part instance` retrieved
    const lCurrentChain : PartInstanceInfoInterface = lPartInstanceInfos[0];

    // iterate over the metadata infos
    const lAllInstanceMetadata : Array<AncestryInstanceMetadataInterface> = lCurrentChain.getAncestorInstanceInfos();

    // number of items 
    const lNbAncestors : number = lAllInstanceMetadata.length;
    const lOffsetToPartInstance : number = lNbAncestors - 1;
    // we get the `part` metadata of the given `part instance` (and not their parents - grand parents) => lNbAncestors-1
    const lCurrentInstanceInfos : AncestryInstanceMetadataInterface = lAllInstanceMetadata[lOffsetToPartInstance];
    const lPartMetadataDocuments : Array<DocumentContentInterface> = lCurrentInstanceInfos.getPartMetadataDocuments();
    if (lPartMetadataDocuments.length === 0)
    {
        console.log('this part instance has no part metadata documents');
        return;
    }
    // and we only care with the first document, but many documents may be attached
    const lPartMetadata : Object = lPartMetadataDocuments[0].getDocumentContent();
    // some fancy output
    console.log(JSON.stringify(lPartMetadata));

    // get the visibility info in order to get information about the `part instance`
    if (lCurrentInstanceInfos.isDisplayable())
    {
        console.log('this part instance is displayable');
    }
};

// trigger the retrieval
lIdCardGetterInterface.retrieveIdCard(lPartInstanceId, lVisibilityContext);

Copy

or with async calls :

/** 
 * Sample to illustrate the asynchronous use of an IdCardGetterInterface with the parsing of
 * PartInstanceInfoInterface to display some information about a part instance.
 */
import {
    WorkingSetInterface, IdCardGetterInterface, AsyncPartInstanceInfoResult,
    AsyncResultReason, PartInstanceInfoInterface, DataSessionInterface, AncestryInstanceMetadataInterface, DocumentContentInterface
} from 'generated_files/documentation/appinfiniteapi';

// the DataSessionInterface has been created previously and is connected
let lDataSession : DataSessionInterface;
// created previously
let lVisibilityContext : WorkingSetInterface;
// the `part instance id` to get
let lPartInstanceId : number;
// what to do when we have retrieved id card information ?

// create an idCardGetter
const lIdCardGetterInterface : IdCardGetterInterface = lDataSession.createIdCardGetter();

const fetchIdCard = async () : Promise<void> =>
{
    // trigger the retrieval
    const lResult : AsyncPartInstanceInfoResult = await lIdCardGetterInterface.asyncRetrieveIdCard(lPartInstanceId, lVisibilityContext);
    if (lResult.reason !== AsyncResultReason.ARR_Success) {
        // do nothing in case of error
        // perhaps some GUI code ?
    }

    const lPartInstanceInfos : Array<PartInstanceInfoInterface> | undefined = lIdCardGetterInterface.getPartInstanceInfos();
    console.assert(lPartInstanceInfos === lResult.value);
    if (!lPartInstanceInfos || lPartInstanceInfos.length !== 1)
    {
        // no data (isCancelled ?)
        return;
    }
    // we required only one `part instance`, as such, only one result should be retrieved
    // iterate over the instantiation chain, but take the first chain since one `part instance` retrieved
    const lCurrentChain : PartInstanceInfoInterface = lPartInstanceInfos[0];

    // get all metadata hierarchy
    const lAllInstanceMetadata : Array<AncestryInstanceMetadataInterface> = lCurrentChain.getAncestorInstanceInfos();

    // number of items 
    const lNbAncestors : number = lAllInstanceMetadata.length;
    const lOffsetToPartInstance : number = lNbAncestors - 1;

    // we get the `part` metadata of the given `part instance` (and not their parents - grand parents) => lNbAncestors-1
    const lCurrentInstanceInfos : AncestryInstanceMetadataInterface = lAllInstanceMetadata[lOffsetToPartInstance];
    const lPartMetadataDocuments : Array<DocumentContentInterface> = lCurrentInstanceInfos.getPartMetadataDocuments();
    if (lPartMetadataDocuments.length === 0)
    {
        console.log('this part instance has no part metadata documents');
        return;
    }
    // and we only care with the first document, but many documents may be attached
    const lPartMetadata : Object = lPartMetadataDocuments[0].getDocumentContent();
    // some fancy output
    console.log(JSON.stringify(lPartMetadata));

    // get the visibility info in order to get information about the `part instance`
    if (lCurrentInstanceInfos.isDisplayable())
    {
        console.log('the last child of the part instance is displayable');
    }
};

fetchIdCard();

Copy

Please make sure the destination browser supports promises before using async calls.

See

• IdCardGetterInterfaceSignal
• PartInstanceInfoInterface
• AncestryInstanceMetadataInterface