All Frameworks  Class Hierarchy  This Framework  Next  Indexes

CATxPDMInterfaces Interface CATIxPDMItem

System.IUnknown
  |
  +---System.IDispatch
    |
    +---System.CATBaseUnknown
      |
      +---CATIxPDMItem
 

Usage: an implementation of this interface is supplied and you must use it as is. You should not reimplement it.


interface CATIxPDMItem

Interface to access any V5 item that can be stored in an external File PDM system.
Role: This interface proposes an unified view of any V5 item that can be stored in an external File PDM system.

An item is a C++ object, handled by the current interface, which is associated with a file. This file can:

To retrieve a first item instance:

Once you have an item instance, use the CATIxPDMItem methods to get all needed information. Then use the CATIxPDMItem.GetChildrenItems method to navigate between various items.

Never compare two item pointers or handlers, because you can have several instances of item representing the same file (loaded in session or not for example), always use the Compare method.

Some methods work only on loaded items. To load an item, use the CATxPDMSessionServices.LoadItemInSession method.

All the methods pre-requisites the PX1 license

See also:
CATIxPDMSession, CATxPDMFileServices, CATxPDMSessionServices


Method Index


o CanBeLoaded(CATBoolean&)
Checks if the item can be loaded in session.
o Compare(CATIxPDMItem_var&)
Checks if two items are describing the same file.
o GeneratePreview(CATUnicodeString&,CATUnicodeString&)
Generates a preview file according to the given format.
o GetChildrenItems(CATListValCATIxPDMItem_var&,CATLISTP(CATMathTransformation)&)
Returns all children of the item.
o GetDocFileName(CATUnicodeString&)
Retrieves the full path of the item.
o GetDocId(CATIDocId*&)
Retrieves the identifier of the item.
o GetItemType(CATUnicodeString&)
Retrieves the real type of the item.
o GetLastSavePath(CATUnicodeString&)
Retrieves the path used during the last save of an item.
o GetLastSaveVersion(CATUnicodeString&)
Retrieves the last save version of an item.
o GetProperty(CATUnicodeString&,CATUnicodeString&)
Reads a property value.
o GetPropertyNames(CATListOfCATUnicodeString&)
Retrieves the property name list for the item.
o GetReadOnlyStatus(CATBoolean&)
Reads the access status (Read Only or Read/Write) of the item.
o NeedToBeSaved(CATBoolean&)
Checks if the item needs to be saved.
o SetProperty(CATUnicodeString&,CATUnicodeString&)
Sets a property value.

Methods


o CanBeLoaded
public virtual HRESULT CanBeLoaded(CATBoolean& oCanBeLoaded) = 0
Checks if the item can be loaded in session.
Role:This method checks if the file associated with the item can be loaded in session. There is no check on compatibility with pointing items already loaded in session.
Parameters:
oCanBeLoaded
The returned status. The value is:
  • TRUE: If the file is already loaded in session, or otherwise, if the file exists on the disk.
  • FALSE: If the file is not loaded, and the file does not exist on the disk.

The method does not guaranty that in case of TRUE answser, the file could be effectively loaded in session.

Returns:
  • S_OK: The status is successfully returned. oCanBeLoaded can be TRUE or FALSE
  • S_FALSE: The file is already loaded in session. In this case it it not necessary to check oCanBeLoaded, its value is always TRUE
    • InputERR_1123:: This non CATIA document can never be loaded
o Compare
public virtual HRESULT Compare( const CATIxPDMItem_var& ixPDMItemToCompare) = 0
Checks if two items are describing the same file.
Role:Direct handler comparison can not be used because you can have an item representing the non loaded file and another for the item loaded in session.
Parameters:
ixPDMItemToCompare
This item to compare with the current one.
Returns:
  • S_OK: The items are exactly the same.
  • S_FALSE: The items are representing the same file with different status (loaded or not for example).
  • E_FAIL: The items are different.
o GeneratePreview
public virtual HRESULT GeneratePreview( const CATUnicodeString& iFormat,
CATUnicodeString& oPreviewFileName) = 0
Generates a preview file according to the given format.
Role:This method generates a file containing an image of the file associated with the item. This image is a preview of the file.

This method does not require that the file is loaded in session.

Parameters:
iFormat
The generated file format. You can only use one among those:
  • jpg
  • bmp
  • tif
  • png
oPreviewFileName
The output file name of the generated preview file. The output file is generated at the same location as the file associated with the item. The name of the preview file is the name of the file file associated with the item + extension of the format.

Example: If the file associated with the item is

  • Windows: c:\temp\Design\MyDesign.CATPart
  • Unix: /temp/Design/MyDesign.CATPart .
The output preview file ( with jpeg format) will be
  • Windows:c:\temp\Design\MyDesign.CATPart.jpg
  • Unix:/temp/Design/MyDesign.CATPart.jpg
Returns:
  • S_OK: The preview file is successfully generated.
  • E_FAIL: The method has failed. The possible returned errors (listed by their identifier) are:
    • InputERR_1002:
    • Internal error.
    • InputERR_1004:
    • Internal error.
    • InputERR_1114:
    • Requested format is not supported.
    • InputERR_1115:
    • Impossible to write file.
    • InputERR_1116:
    • The file is not loaded in session, and it does not exist on disk.
    • InputERR_1117:
    • Not available on V4 data.
o GetChildrenItems
public virtual HRESULT GetChildrenItems(CATListValCATIxPDMItem_var& oChildrenList,
CATLISTP(CATMathTransformation)& oChildrenLocationList) = 0
Returns all children of the item.
Role:This method retrieves all the child items from the current one. This method requires that the file associated with the current item is loaded in session.
Parameters:
oChildrenList
The children list, those items could be loaded or not.
oChildrenLocationList
The list of positioning matrix for Product Structure children. The size of this list is always equal to the size of the children list. If an element of oChildrenList is not a Product the corresponding matrix pointer is null.

Caution:After calling the method, and in all cases you must check all elements of the oChildrenLocationList. If one is non null, the pointer must be released.

Returns:
  • S_OK: The children list is successfully computed.
  • E_FAIL: The method has failed. The possible returned errors (listed by their identifier) are:
    • InputERR_1004:
    • Internal error.
    • InputERR_1116:
    • The file is not loaded in session.
o GetDocFileName
public virtual HRESULT GetDocFileName(CATUnicodeString& oDocFilePathName) = 0
Retrieves the full path of the item.
Role:This method retrieves the full path of the file associated with the item. It does not require that the file is loaded in session.
Parameters:
oDocFilePathName
The full path of the file associated with the item (with directory name and file extension, for example C:\Temp\Part1.CATPart). If the file has never been saved, the default name of the file is returned.
Returns:
  • S_OK: The full path is successfully returned.
  • E_FAIL: Impossible to retrieve the full path
o GetDocId
public virtual HRESULT GetDocId(CATIDocId*& oDocId) = 0
Retrieves the identifier of the item.
Role:This method retrieves the identifier of the file associated with the item. It does not require that the file is loaded in session.
Parameters:
oDocId
The identifier of the file associated with the item. The caller must release oDocId after its usage.
Returns:
  • S_OK: The identifier is successfully returned.
  • E_FAIL: The file is not loaded in session, and it does not exist on disk.
o GetItemType
public virtual HRESULT GetItemType(CATUnicodeString& oFileType) = 0
Retrieves the real type of the item.
Role:This method retrieves the real of the file associated with the item. It allows you checking if a file with a V5 extension is really a V5 file.

This method does not require that the file is loaded in session.

Parameters:
oFileType
The type of the file associated with the item. The returned string can be:
  • For a file with a V5 extension:
    • For a "right" V5 file : CATPart, CATProduct, CATDrawing,....
    • It is the real type of the file that is returned. Even if you change the extension (renaming xx.CATPart in yy.CATProduct), the real type (CATPart) will be returned.

    • Otherwise, not a "right" V5 file: NotAV5File
    • For example, suppose a txt file renamed myTextFile.CATPart. In this case, the string NotAV5File is returned, and not CATPart

  • Otherwise, a file without a V5 extension: the file extension without any check.
    • For a "right" V5 file : CATPart, CATProduct, CATDrawing,....
    • Ex: for Part3 and Part3.titi, two Part documents, CATPart will be returned

    • Otherwise, not a "right" V5 file: The file extension without any check
Returns:
  • S_OK: A V5 file type is successfully returned.
  • S_FALSE: The NotAV5File type is successfully returned.
  • E_FAIL: The file is without extension and the file is not a V5 file.
  • E_FAIL: The file is not loaded in session, and it does not exist on disk.
o GetLastSavePath
public virtual HRESULT GetLastSavePath(CATUnicodeString& oSavePath) = 0
Retrieves the path used during the last save of an item.
Role:This method retrieves the full path of the file associated with the item used during the last save operation. It does not require that the file is loaded in session.
Parameters:
oSavePath
The full path of the file associated with the item during the last save. The file must be a V5 file.

This path can be a Windows path, a Unix path (it depends on the last save has been performed on Unix or Windows), or a DLName. For a DLName, this is the displayed name of the DLName.

The returned path does not change if

  • The file is renamed or moved directly on disk.
  • The file is renamed or copied during Send To operations

Returns:
  • S_OK: The path is successfully returned.
  • S_FALSE: The file has never been saved.
  • E_FAIL: The file is not loaded in session, and it does not exist or there is no read access right.
  • E_FAIL: The file is not a V5 file.
o GetLastSaveVersion
public virtual HRESULT GetLastSaveVersion(CATUnicodeString& oVersion) = 0
Retrieves the last save version of an item.
Role:This method retrieves the version used during the last save operation on the file associated with the item. It does not require that the file is loaded in session.
Parameters:
oVersion
The last save version of the file. This information is only accessible for V5 files, and those created from V5R10 and after. The version is a none NLS string with the following format:

<Version>V</Version><Release>R</Release><ServicePack>SP</ServicePack><HotFix>HF</HotFix>

where:

  • V is the version number.
  • R is the release number.
  • SP is the service pack number. If zero, it a GA level
  • HF is the hotfix number; If zero it is not an hotfix. The sub string <HotFix>HF</HotFix>
  • is returned only in V5R14 and upper level.

First example: V5R11 :
<Version>5</Version><Release>11</Release><ServicePack>0</ServicePack>

Second example: V5R14SP3 :
<Version>5</Version><Release>14</Release><ServicePack>13</ServicePack><HotFix>0</HotFix>

For a file saved before the V5R10, the returned string is empty.

The returned path does not change if:

  • The file is renamed or moved directly on disk.
  • The file is renamed or copied during Send To operations

Returns:
  • S_OK: The version has been successfully retrieved.
  • S_FALSE: The version is not available on the V5 file (previous to V5R10).
  • S_FALSE: The file has never been saved.
  • E_FAIL: The file is not loaded in session, and it does not exist or there is no read access right.
  • E_FAIL: The file is not a V5 file.
o GetProperty
public virtual HRESULT GetProperty( const CATUnicodeString& iPropName,
CATUnicodeString& oPropValue) = 0
Reads a property value.
Role:This method reads a property defined in the file associated with the item. This method requires that the file exists in session.
Parameters:
iPropName
The property name.
The standard properties are:
  • CN_PART_NUMBER
  • CN_REVISION
  • CN_DEFINITION
  • CN_NOMENCLATURE
  • CN_DESCRIPTIONREF
  • CN_SOURCE
  • CN_VOLUME
  • CN_MASS
  • CN_SURFACE

Other properties are user defined properties.
oPropValue
The property value
Returns:
  • S_OK: The property value is successfully computed.
  • E_FAIL: The method has failed. The possible returned errors (listed by their identifier) are:
    • InputERR_1116:: The file is not loaded in session
    • InputERR_1120:: The property name has not been found
o GetPropertyNames
public virtual HRESULT GetPropertyNames(CATListOfCATUnicodeString& oListPropertyNames) = 0
Retrieves the property name list for the item.
Role:This method returns the list of available properties on this item including standard properties (CN_PART_NUMBER...) and user properties. The file associated with the item needs to be loaded before.
Parameters:
oListPropertyNames
The list of property names.
Returns:
  • S_OK: The property name list is successfully computed.
  • E_FAIL: The method has failed. The possible returned errors (listed by their identifier) are:
    • InputERR_1116:: The file is not loaded in session
o GetReadOnlyStatus
public virtual HRESULT GetReadOnlyStatus(CATBoolean& oIsReadOnly) = 0
Reads the access status (Read Only or Read/Write) of the item.
Role:This method retrieves the access status of the file associated with the item. The status is based on the file access right read on the disk. This method does not require that the file is loaded in session.

During the session, if the status is changed on disk, the status returned by this method does not take into account the new right. If you need the "real" status, invoke the CATxPDMSessionServices.RefreshItemInformation method before the current one.

Parameters:
oIsReadOnly
The read only status. If the file is 'Read Only' the returned value is TRUE otherwise FALSE.

If the file does not exist yet on the disk, but exists in session (a new V5 file), the right is 'Read/Write'.

Caution: Interactively, if the 'Read Only' check button has been selected in the 'File/Open' dialog box, the returned value is TRUE whathever the file access right on the disk.

Returns:
  • S_OK: The access status is successfully returned.
  • E_FAIL: The file is not loaded in session, and it does not exist on disk.
o NeedToBeSaved
public virtual HRESULT NeedToBeSaved(CATBoolean& oNeedToBeSaved) = 0
Checks if the item needs to be saved.
Role:This method enables you to know if the file associated with the item needs to be saved or not. This method requires that the file exists in session.
Parameters:
oNeedToBeSaved
The returned status. The value is TRUE if the file has been modified in the session after the last save operation, or if it is a new file never saved. Otherwise, the returned value is FALSE.
Returns:
  • S_OK: The status is successfully returned.
  • E_FAIL: The file does not exist in session.
o SetProperty
public virtual HRESULT SetProperty( const CATUnicodeString& iPropName,
const CATUnicodeString& iPropValue) = 0
Sets a property value.
Role:This method modifies a property defined in the file associated with the item. This method requires that the file exists in session. Do not forget, after one or several property value modifications to save the items using the CATxPDMSessionServices.SaveSessionToDirectory method.
Parameters:
iPropName
The property name
Standard properties are:
  • CN_PART_NUMBER
  • CN_REVISION
  • CN_DEFINITION
  • CN_NOMENCLATURE
  • CN_DESCRIPTIONREF
  • CN_SOURCE

Other properties are user defined properties.
iPropValue
The property value
Returns:
  • S_OK: Property names successfully valuated.
  • E_FAIL: The method has failed. The possible returned errors (listed by their identifier) are:
    • InputERR_1116: The file is not loaded in session
    • InputERR_1120: The property name has not been found or cannot be modified.

This object is included in the file: CATIxPDMItem.h
If needed, your Imakefile.mk should include the module: CATxPDMInterfaces

Copyright © 2003, Dassault Systèmes. All rights reserved.