PLMSRMExposedServices CATPLMExchangeChannelServices

Usage: you must use this class as is. You should never derive it.

public class CATPLMExchangeChannelServices

Class representing services to manage a PLM Channel.

Role: A PLM Channel is an exchange context created between two specific repositories in order to allow optimized back and forth data exchange and ownership transfers.

Before exchanging data, the PLM Channel must be correctly initialized on both sides:

  1. The distant site generates a business card with the method and sends it to the local site in order to ask it to initiate the PLM Channel.
  2. The local site initializes the PLM Channel from the received business card with the method and sends an exchange request file to the distant site to inform it that a PLM Channel is open and ready for use on the local site.
  3. The distant site finalizes the PLM Channel creation (by accepting or refusing it) with the method and sends a confirmation file to the local site to inform it of its decision. This confirmation file contains the accept or refuse status.
  4. The local site acknowledges the confirmation file with the method. If the distant site has refused the PLM Channel creation then the local site can delete the initialized PLM Channel with the method.

Once the PLM Channel is created on both sides with an Active data can be exchanged between the two sites using the or , and methods.
The status of a PLM Channel can be determined with the method.
The site ownership information can be retrieved for a given list of PLM Entities with the method.

Example: 
  
CATPLMExchangeChannelServices* exchangeChannelServices = new CATPLMExchangeChannelServices();
  if (exchangeChannelServices)
  {
     HRESULT Rc = exchangeChannelServices->xxx();
     .
     .
     .
     exchangeChannelServices->Release();
     exchangeChannelServices = NULL;
  }
See also:

Constructor and Destructor Index


o CATPLMExchangeChannelServices()
Constructs an empty PLM Channel services class.
o CATPLMExchangeChannelServices(CATPLMExchangeChannelServices&)
Copy Constructor.
o ~CATPLMExchangeChannelServices()
Destructs a PLM Channel services class.

Method Index


o AcknowledgeChannelCreation(CATUnicodeString&,CATString&,CATUnicodeString&)
Processes on local site the PLM Channel creation confirmation from distant site.
o AcknowledgeExchange(CATUnicodeString&,CATString&,CATUnicodeString&)
Completes the exchange process.
o FinalizeChannelCreation(CATUnicodeString&,CATBoolean&,CATUnicodeString&,CATString&)
Creates the PLM Channel on distant site from the exchange request file generated by the local site.
o GenerateBusinessCard(CATUnicodeString&)
Generates a Business Card.
o GetChannelStatus(CATString&,CATPLMChannelStatus&,CATPLMChannelStatus&)
Retrieves the current status of the PLM Channel on both sites.
o GetSiteInformation(CATLISTP(CATIAdpPLMIdentificator)&,CATLISTP(CATPLMSiteStatus)&)
Retrieves the site ownership information for a given list of PLM Entities.
o InitializeChannelCreation(CATUnicodeString&,CATUnicodeString&,CATString&)
Creates the PLM Channel on local site from the Business Card of the distant repository.
o MergeAcknowledgementFile(CATUnicodeString&,CATString&,CATUnicodeString&,CATListOfCATUnicodeString&)
Merge acknowledgement files of a defined PLM Channel.
o PublishExchange(CATString&,CATListPtrCATIAdpPLMIdentificator&,CATTime&,CATBoolean&,CATUnicodeString&)
Publishes data through a connected PLM Channel.
o PublishExchangeWithoutExpand(CATString&,CATListPtrCATIAdpPLMIdentificator&,CATTime&,CATBoolean&,CATUnicodeString&)
Publishes data through a connected PLM Channel without expanding the structure.
o RemoveExchangeChannel(CATString&,CATUnicodeString&)
Removes the PLM Channel on a site.
o SetAcknowledgementPathForPublishOptimization(CATUnicodeString&)
Set the path of an acknowledgement to be used for publish optimization.
o SetMultipleBriefcaseDirectoryForSynchronize(CATUnicodeString&)
Set the directory where briefcases will be used for synchronization.
o SetMultipleBriefcaseDirectoryForSynchronize(CATUnicodeString&,CATPLMChannelMultipleBriefcaseOption)
Set the directory where briefcases will be used for synchronization.
o SetMultipleBriefcaseParametersForPublish(int,CATUnicodeString&)
Set the parameters to enable the split of the published briefcase during publish operation.
o SetOptionsForSynchronizeExchange(CATBoolean&,CATPLMChannelOption&)
Sets the options to manage the synchronization of a PLM Channel.
o SetReportFilePath(CATUnicodeString&)
Set the file path to generate a report for publish or synchronize operation.
o SynchronizeExchange(CATUnicodeString&,CATUnicodeString&,CATString&,CATString&)
Synchronizes data through a connected PLM Channel.
o operator=(CATPLMExchangeChannelServices&)
Assignement operator from a CATPLMExchangeChannelServices instance.

Enumerated Type Index


o CATPLMChannelMultipleBriefcaseOption
Options to manage at synchronization error in case of Multiple briefcases mode.
o CATPLMChannelOption
Option to solve conflict during synchronization.
o CATPLMChannelStatus
Status of each PLM Channel site: local and distant.

Constructor and Destructor


o CATPLMExchangeChannelServices
public CATPLMExchangeChannelServices()
Constructs an empty PLM Channel services class.
o CATPLMExchangeChannelServices
public CATPLMExchangeChannelServices( )
Copy Constructor.
o ~CATPLMExchangeChannelServices
public virtual ~CATPLMExchangeChannelServices()
Destructs a PLM Channel services class.

Methods


o AcknowledgeChannelCreation
public AcknowledgeChannelCreation( const iCreationConfirmFilePath,
oChannelId,
oReport)
Processes on local site the PLM Channel creation confirmation from distant site.
Role: This method processes the confirmation file sent by the distant site and activates or deprecates the PLM Channel accordingly. It generates a report.
Parameters:
iCreationConfirmFilePath
[in] The path of the file containing the creation confirmation. The file must exist and have a PLMBriefcase extension.
oChannelId
[out] The PLM Channel identification (unique identification of the created PLM Channel between local and distant repositories).
oReport
[out] The report generated with the creation or refusal information from the distant site.
Returns:
An HRESULT value.
Legal values:
S_OK
if the creation of the PLM Channel succeeds on both sites.
S_FALSE
if the creation of the PLM Channel has been refused on distant site. In that case, the PLM Channel should be deleted on local site.
E_INVALIDARG
if any of the input paths is invalid.
E_FAIL
if there is any other problem.
o AcknowledgeExchange
public AcknowledgeExchange( const iAcknowledgementFilePath,
oChannelId,
oReport)
Completes the exchange process.
Role: This method completes the exchange process and returns the synchronization status from distant site.
Parameters:
iAcknowledgementFilePath
[in] The path of the file containing the acknowledgement. The file must exist and have a PLMBriefcase extension.
oChannelId
[out] The PLM Channel identification (unique identification of the created PLM Channel between local and distant repositories).
oReport
[out] The report generated with the synchronization status from distant site.
Returns:
An HRESULT value.
Legal values:
S_OK
if the synchronization was correctly done.
E_INVALIDARG
if any of the input paths is invalid.
E_FAIL
if there is any other problem.
o FinalizeChannelCreation
public FinalizeChannelCreation( const iExchangeRequestFilePath,
const iForceRefuse,
iCreationConfirmationFilePath,
oChannelId)
Creates the PLM Channel on distant site from the exchange request file generated by the local site.
Role: This method finalizes the PLM Channel creation on distant site and generates a confirmation file accepting or refusing the PLM Channel connexion.
Parameters:
iExchangeRequestFilePath
[in] The path of the file containing the exchange request. The file must exist and have a PLMBriefcase extension.
iForceRefuse
[in] A parameter to refuse the creation of the PLM Channel.
Legal values:
TRUE
the PLM Channel creation is automatically refused.
FALSE
the PLM Channel creation is accepted.
iCreationConfirmationFilePath
[in] The path of the file where to generate the confirmation of the PLM Channel creation. It must correspond to an existing directory and the file must have a PLMBriefcase extension.
oChannelId
[out] The Channel identification (unique identification of the created PLM Channel between local and distant repositories).
Returns:
An HRESULT value.
Legal values:
S_OK
if the creation of the PLM Channel succeeds.
E_ACCESSDENIED
if the file where to write the confirmation already exists in Read Write mode.
E_INVALIDARG
if any of the input paths is invalid.
E_FAIL
if there is any other problem.
o GenerateBusinessCard
public GenerateBusinessCard( const iBusinessCardPath)
Generates a Business Card.
Role: This method is used to generate a Business Card to share the site identification. It writes into the input file the site identification of the VPLM database to which the process is connected to.
Parameters:
iBusinessCardPath
[in] The path of the file where to generate the Business Card. It must correspond to an existing directory and the file must have a xml extension.
Returns:
An HRESULT value.
Legal values:
S_OK
if the generation of the Business Card succeeds.
E_ACCESSDENIED
if the file where to write the Business Card already exists in Read Write mode.
E_INVALIDARG
if the file where to write the Business Card is invalid.
E_FAIL
if there is any other problem.
o GetChannelStatus
public GetChannelStatus( const iChannelId,
oLocalSiteStatus,
oDistantSiteStatus)
Retrieves the current status of the PLM Channel on both sites.
Role: For a specific PLM Channel identifier, it retrieves the status of each site.
Parameters:
iChannelId
[in] The PLM Channel identification (unique identification of the created PLM Channel between local and distant repositories).
oLocalSiteStatus
[out] The status of the local site
oDistantSiteStatus
[out] The status of the distant site.
Returns:
An HRESULT value.
Legal values:
S_OK
if the status for both sites is successfully retrieved.
E_FAIL
if there is any problem.
o GetSiteInformation
public GetSiteInformation( const iPLMEntitiesIdsList,
oSiteStatusList)
Retrieves the site ownership information for a given list of PLM Entities.
Role: This method returns a list of site ownership status corresponding to the input list of PLM Entities identifiers.
Parameters:
iPLMEntitiesIdsList
[in] The list of identificators of the PLM Entities for which the site ownership information status is asked.
oSiteStatusList
[out] The list of site ownership information status corresponding to the input list. The output list has the same size as the input list.
Returns:
An HRESULT value:
Legal values:
S_OK
if the status are correctly retrieved.
E_INVALIDARG
if any input arguments are invalid. In that case, the output list is null.
E_FAIL
if information cannot be retrieved. In that case, the output list is null. A CATError is associated.
o InitializeChannelCreation
public InitializeChannelCreation( const iBusinessCardPath,
iExchangeRequestFilePath,
oChannelId)
Creates the PLM Channel on local site from the Business Card of the distant repository.
Role: This method initializes the PLM Channel creation on the local site and generates an exchange request file to inform the distant site.
Parameters:
iBusinessCardPath
[in] The path of the file containing the Business Card of the distant site. The file must exist and have a xml extension.
iExchangeRequestFilePath
[in] The path of the file where to generate the exchange request. It must correspond to an existing directory and the file must have a PLMBriefcase extension.
oChannelId
[out] The PLM Channel identification (unique identification of the created PLM Channel between local and distant repositories).
Returns:
An HRESULT value.
Legal values:
S_OK
if the initialization of the Channel succeeds.
E_ACCESSDENIED
if the file where to write the exchange request already exists in Read Write mode.
E_INVALIDARG
if any of the input paths is invalid.
E_FAIL
if there is any other problem.
o MergeAcknowledgementFile
public MergeAcknowledgementFile( const iInputDirectoryPath,
const iChannelId,
const iAcknowledgementFilePath,
oMergedFileList)
Merge acknowledgement files of a defined PLM Channel.
Role: This method merges acknowledgement files located in one input directory and belonging to one specified PLM Channel.
Parameters:
iInputDirectoryPath
[in] The path of the directory containing the acknowledgement file to be merged.
iChannelId
[in] The PLM Channel identification.
iAcknowledgementFilePath
[in] The path of the file containing the acknowledgement. The file must not exist and have a PLMBriefcase extension.
oMergedFileList
[out] List of acknoledgement files merged.
Returns:
An HRESULT value.
Legal values:
S_OK
if the Acknowledgement File Merge was correctly done.
S_FALSE
No acknowledgement file to merge found.
E_INVALIDARG
if any of the input paths is invalid.
E_FAIL
if there is any other problem.
o PublishExchange
public PublishExchange( const iChannelId,
const iObjectsIds,
const iDate,
const iTransferOwnership,
const iBriefcaseFilePath)
Publishes data through a connected PLM Channel.
Role: This method generates a briefcase file containing the data to exchange with the distant site. It enables to transfer the ownership of the data to the distant site.
Parameters:
iChannelId
[in] The PLM Channel identification (unique identification of the created PLM Channel between local and distant repositories).
iObjectsIds
[in] The optional list of PLM Components identificators to be exchanged. The whole structure is automatically added to the exchange scope. Applied materials, Design Tables and attached documents are exported along with the PLM Components of the input list.
iDate
[in] An optional parameter to filter data in order to reduce the size of the exchange. All Product representations with a modification date inferior to this date are excluded from the exchange file.
iTransferOwnership
[in] A parameter that allows to transfer or not the site ownership of the published data. If TRUE, the site ownership is transmitted to the distant site.
iBriefcaseFilePath
[in] The path of the file where to generate the briefcase. It must correspond to an existing directory and the file must have a PLMBriefcase extension.
Returns:
An HRESULT value.
Legal values:
S_OK
if the publication succeeds.
E_ACCESSDENIED
if the file where to write the briefcase already exists in Read Write mode.
E_INVALIDARG
if any of the input paths is invalid.
E_FAIL
if there is any other problem.
o PublishExchangeWithoutExpand
public PublishExchangeWithoutExpand( const iChannelId,
const iObjectsIds,
const iDate,
const iTransferOwnership,
const iBriefcaseFilePath)
Publishes data through a connected PLM Channel without expanding the structure.
Role: This method generates a briefcase file containing the data to exchange with the distant site. It enables to transfer the ownership of the data to the distant site.
Parameters:
iChannelId
[in] The PLM Channel identification (unique identification of the created PLM Channel between local and distant repositories).
iObjectsIds
[in] The optional list of PLM Components identificators to be exchanged. No expand operation is performed on the selected Product structure. Applied materials, Design Tables and attached documents are exported along with the PLM Components of the input list.
iDate
[in] An optional parameter to filter data in order to reduce the size of the exchange. All Product representations with a modification date inferior to this date are excluded from the exchange file.
iTransferOwnership
[in] A parameter that allows to transfer or not the site ownership of the published data. If TRUE, the site ownership is transmitted to the distant site.
iBriefcaseFilePath
[in] The path of the file where to generate the briefcase. It must correspond to an existing directory and the file must have a PLMBriefcase extension.
Returns:
An HRESULT value.
Legal values:
S_OK
if the publication succeeds.
E_ACCESSDENIED
if the file where to write the briefcase already exists in Read Write mode.
E_INVALIDARG
if any of the input paths is invalid.
E_FAIL
if there is any other problem.
o RemoveExchangeChannel
public RemoveExchangeChannel( const iChannelId,
iDeletionFilePath)
Removes the PLM Channel on a site.
Role: This method should be called on each site to remove the PLM Channel.
Parameters:
iChannelId
[in] The PLM Channel identification (unique identification of the created PLM Channel between local and distant repositories).
iDeletionFilePath
[in] The path of the file where to generate the deletion information to be sent to distant site. The path must correspond to an existing directory and the file must have a PLMBriefcase extension.
Returns:
An HRESULT value.
Legal values:
S_OK
if the PLM Channel is correctly removed on the site with correct information in the deletion file.
E_ACCESSDENIED
if the file where to write the deletion information already exists in Read Write mode.
E_INVALIDARG
if the PLM Channel identification or the input path is invalid.
E_FAIL
if there is any problem.
o SetAcknowledgementPathForPublishOptimization
public SetAcknowledgementPathForPublishOptimization( const iAcknowledgementFilePath)
Set the path of an acknowledgement to be used for publish optimization.
Role: This method changes the behaviour of the publish command. The acknowledgement contains information regarding distant object allowing the publish method to perform optimization. This method should be used before publish to be effective.
Parameters:
iFilePath
[in] The path where the acknowledgement is located.
Returns:
An HRESULT value.
Legal values:
S_OK
if the operation succeeds.
E_ACCESSDENIED
if the directory is not readable or is empty.
E_FAIL
if there is any other problem.
o SetMultipleBriefcaseDirectoryForSynchronize
public SetMultipleBriefcaseDirectoryForSynchronize( const iDirectory)
Set the directory where briefcases will be used for synchronization.
Role: This method is used when the publication is done by calling the This method should be used before synchronization to be effective.
Parameters:
iDirectory
[in] The directory where briefcases to be synchronized are located.
iSynchronizationStrategy
[in] Enables to define what to do in case of error at synchronization.
Returns:
An HRESULT value.
Legal values:
S_OK
if the operation succeeds.
E_ACCESSDENIED
if the directory is not readable or is empty.
E_FAIL
if there is any other problem.
o SetMultipleBriefcaseDirectoryForSynchronize
public SetMultipleBriefcaseDirectoryForSynchronize( const iDirectory,
iSynchronizationStrategy)
Set the directory where briefcases will be used for synchronization.
Role: This method is used when the publication is done by calling the This method should be used before synchronization to be effective.
Parameters:
iDirectory
[in] The directory where briefcases to be synchronized are located.
iSynchronizationStrategy
[in] Enables to define what to do in case of error at synchronization.
Returns:
An HRESULT value.
Legal values:
S_OK
if the operation succeeds.
E_ACCESSDENIED
if the directory is not readable or is empty.
E_FAIL
if there is any other problem.
o SetMultipleBriefcaseParametersForPublish
public SetMultipleBriefcaseParametersForPublish( const iNumberOfComponentPerBriefcase,
const iDirectory)
Set the parameters to enable the split of the published briefcase during publish operation.
Role: This method changes the behaviour of the publish method and generates a set of briefcase files instead of an unique briefcase file. The number of Component per briefcase is driven by an integer. Each briefcase has an automatically generated name. This method should be called before publish to be effective.
Parameters:
iNumberOfComponentPerBriefcase
[in] an positive integer that drives the number of PLMComponent per briefcase. This is an approximative number: The number of elements per briefcase is increased for integrity purpose.
iDirectory
[in] The directory where briefcases will be published..
Returns:
An HRESULT value.
Legal values:
S_OK
the operation succeeds.
E_ACCESSDENIED
if the directory where to write the briefcase already exists in Read Write mode.
E_INVALIDARG
if iNumberOfComponentPerBriefcase is not a strictly positive integer or if the input path is not empty
E_FAIL
if there is any other problem.
o SetOptionsForSynchronizeExchange
public SetOptionsForSynchronizeExchange( iAllowWeakenedEntities,
iOptionOnConflict)
Sets the options to manage the synchronization of a PLM Channel.
Role: This method allows the user to change the default behaviour of the method. It is an optional method.

It is useful when:

Parameters:
iAllowWeakenedEntities
[in] The option to authorize or not the creation of weakened entities in the repository during the synchronization. When importing a PLM entity from a higher dictionary level, unknown attributes and unsupported extensions are ignored. This causes the degradation of the PLM entity which is called a weakened entity. By default the option is set to FALSE, meaning that the method fails if data degradation is detected during the synchronization. To force the creation of weakened entities, the option should be set to TRUE.
iOptionOnConflict
[in] The option to solve conflict when the briefcase to import contains data with a new history branch (due to the Repair Site Ownership tool). By default the option is set to
ErrorOnConflict, meaning that the method fails if there is a conflict on data. The other possible values are:
KeepLocal
if the user wants to keep its local version of the data.
TakeIncoming
if the user wants to overwrite its data with the new incoming one.

By setting the option to KeepLocal or to TakeIncoming, the user ensures that the SynchronizeExchange method does not fail because of a conflict problem.
Returns:
An HRESULT value.
Legal values:
S_OK
if the method succeeds.
E_INVALIDARG
if any of the input arguments is invalid.
E_FAIL
if there is any other problem.
o SetReportFilePath
public SetReportFilePath( const iFilePath)
Set the file path to generate a report for publish or synchronize operation.
Role: This method changes the behaviour of the publish or synchronize methods. It generates a report that can be read through interfaces This method should be used before publish or synchronize to be effective.
Parameters:
iFilePath
[in] The path where the report will be generated.
Returns:
An HRESULT value.
Legal values:
S_OK
if the operation succeeds.
E_ACCESSDENIED
if the directory is not readable or is empty.
E_FAIL
if there is any other problem.
o SynchronizeExchange
public SynchronizeExchange( const iBriefcaseFilePath,
const iAcknowledgementFilePath,
iPLMEnvironment,
oChannelId)
Synchronizes data through a connected PLM Channel.
Role: This method imports a briefcase file containing the data sent by the distant site.
Parameters:
iBriefcaseFilePath
[in] The path of the file containing the briefcase to import. The file must exist and have a PLMBriefcase extension.
iAcknowledgementFilePath
[in] The path of the file where to generate the confirmation of synchronization. It must correspond to an existing directory and the file must have a PLMBriefcase extension. It captures operations done during the synchronization.
iPLMEnvironment
The optional PLM Environment. If not set, the current environment is taken.
oChannelId
[out] The PLM Channel identification (unique identification of the created PLM Channel between local and distant repositories).
Returns:
An HRESULT value.
Legal values:
S_OK
if the synchronization succeeds.
E_ACCESSDENIED
if the file where to write the acknowledgement already exists in Read Write mode.
E_INVALIDARG
if any of the input paths is invalid.
E_FAIL
if there is any other problem.
o operator=
public operator=( )
Assignement operator from a CATPLMExchangeChannelServices instance.
Returns:
An instance of a PLM Channel services class.

Enumerated Types


o CATPLMChannelMultipleBriefcaseOption 
enum CATPLMChannelMultipleBriefcaseOption {
  ExecuteAll,
  StopAtFirstError,
  SkipFirstError
}
Options to manage at synchronization error in case of Multiple briefcases mode. NB: Briefcases are executed in order and when briefcase at position n+1 is synchronized, briefcase at position n will be skipped at next synchronization.
Parameters:
ExecuteAll
This is the default mode for
method and we will try to synchronize all briefcases whatever the fact some briefcases could fail in error.
StopAtFirstError
The
method will stop briefcases synchronization when encounters the first briecase in error. This mode enables to restart synchronization in case of environment issue such as disk full, server stop and administrator could iterate Synchronization till he solves all environment issues.
SkipFirstError
The
method will by-pass first briefcase in error at synchronization and will continue synchronization of other briefcases till we encounter another error. This mode enables to restart synchronization in case an error could not be repaired locally and need a new publish.
o CATPLMChannelOption 
enum CATPLMChannelOption {
  ErrorOnConflict,
  KeepLocal,
  TakeIncoming
}
Option to solve conflict during synchronization.
Parameters:
ErrorOnConflict
The
method fails if there is a conflict on data during the synchronization.
KeepLocal
The local version of the imported PLM entities is kept if there is a conflict on data during the synchronization.
TakeIncoming
The local version of the PLM entities is overwritten by the imported data if there is a conflict on data during the synchronization.
o CATPLMChannelStatus 
enum CATPLMChannelStatus {
  Unknown,
  Active,
  Deleted,
  Refused
}
Status of each PLM Channel site: local and distant.
Parameters:
Unknown
The site is unknown for the PLM Channel identifier.
Active
The site is activated for the PLM Channel identifier.
Deleted
The site does not know the PLM Channel identifier anymore.
Refused
The site has refused the PLM Channel identifier.
This object is included in the file: CATPLMExchangeChannelServices.h
If needed, your Imakefile.mk should include the module: PLMChannelAPI

Copyright © 1999-2014, Dassault Systèmes. All rights reserved.