CIP C++ documentation for class "pfcAsyncConnection"

Class pfcAsyncConnection

# include <pfcAsyncConnection.h> class pfcAsyncConnection : public virtual pfcActionSource { xaideclare(pfcAsyncConnection) ... };

Description

This class represents an asynchronous connection to Creo Parametric.

Method Summary


`static pfcAsyncConnection_ptr`	`Connect (optional xrstring Display, optional xrstring UserID, optional xrstring TextPath, optional xint TimeoutSec)`
	Causes the application to connect to an existing Creo Parametric process running on a host using a specified display. It is intended for use in simple and full asynchronous modes.

`static pfcAsyncConnection_ptr`	`ConnectById (pfcConnectionId_ptr Id, optional xrstring TextPath, optional xint TimeoutSec)`
	Connects to a specific Creo Parametric session by passing the identification string.

`static pfcAsyncConnection_ptr`	`ConnectWS (optional xrstring Display, optional xrstring UserID, optional xrstring WSName, optional xrstring TextPath, optional xint TimeoutSec)`
	Causes the application to connect to an existing Creo Parametric process and to an existing Pro/INTRALINK worksapce running on a host using a specified display. For use in simple and full asynchronous modes.

`void`	`Disconnect (optional xint TimeoutSec)`
	Disconnects the application from the current Creo Parametric process. Creo Parametric will still be running after this call.

`void`	`End ()`
	Terminates and disconnects from the current Creo Parametric process.

`void`	`EventProcess ()`
	Enables your process to respond to listener calls from Creo Parametric. You must call this function within your control loop in order that your application will be able to respond to listener calls. Creo Parametric will be blocked until the application responds to a registered listener.

`xbool`	`ExecuteAsyncJavaMethod (xrstring Class, xrstring Method, pfcArguments_ptr InputArguments, xrstring ClassForUnlock)`
	This is the "JOTK sandbox" to execute methods with full OTK Asynchronous Java access. Can be used only in Java language binding.

`static optional pfcAsyncConnection_ptr`	`GetActiveConnection ()`
	Connection established between your application and Creo Parametric. If your application is connected with Creo Parametric, call this function to get the connection object.

`pfcConnectionId_ptr`	`GetConnectionId ()`
	Extracts the identification handle of the current Creo Parametric process.

`pfcSession_ptr`	`GetSession ()`
	`DEPRECATED: since Creo 4` `SUCCESSOR(S): <reference 3 to unknown entity >` The handle to the session of Creo Parametric for the current active connection.

`void`	`InterruptEventProcessing ()`
	Call this function from within a Creo Parametric callback function to halt a loop currently running in `pfcAsyncConnection::WaitForEvents()`.

`xbool`	`IsRunning ()`
	Determines whether you are currently connected to an actively responding Creo Parametric session.

`static pfcAsyncConnection_ptr`	`Start (xrstring CmdLine, optional xrstring TextPath)`
	Causes the application to spawn and connect to a new Creo Parametric session. For use in simple and full asynchronous modes.

`void`	`WaitForEvents ()`
	Initiates an event loop which will call event processing periodically to handle events returned from Creo Parametric. Applicable only for full asynchronous applications which are not supposed to carry out any tasks while waiting for Creo Parametric events.

Methods Inherited from Class pfcActionSource:: AddActionListener, RemoveActionListener, AddActionListenerWithType

Method Detail

static pfcAsyncConnection_ptr Start (xrstring CmdLine, optional xrstring TextPath)

Causes the application to spawn and connect to a new Creo Parametric session. For use in simple and full asynchronous modes.

Manual References:: Asynchronous Mode: Starting and Stopping Creo Parametric, Asynchronous Mode: Starting and Stopping Creo Parametric, Asynchronous Mode: Setting Up a Noninteractive Session, Asynchronous Mode: General Problems

Parameters:

CmdLine: The full path to the startup command, batch file or script file used to start Creo Parametric.
TextPath: The path under which the message and menu files are held. If no external messaging or menus are needed pass null.

Returns:: Object representing the asynchronous connection.

static pfcAsyncConnection_ptr Connect (optional xrstring Display, optional xrstring UserID, optional xrstring TextPath, optional xint TimeoutSec)

Causes the application to connect to an existing Creo Parametric process running on a host using a specified display. It is intended for use in simple and full asynchronous modes.

If the method locates more than one Creo Parametric session with the appropriate characteristics, it will throw an pfcXToolkitAmbiguous exception.

If you want to connect or reconnect to a specific Creo Parametric session, use the method pfcAsyncConnection::ConnectById(pfcConnectionId_ptr, optional xrstring, optional xint)

The application may only connect to one Creo Parametric session at any time.

Manual References:: Asynchronous Mode: Setting Up a Noninteractive Session, Asynchronous Mode: Setting Up a Noninteractive Session, Asynchronous Mode: General Problems, Geometry Evaluation: Geometry of Surfaces

Parameters:

Display: The name of the display Creo Parametric is using. If this is null, match any display. If this is an empty string, assume the local host.
UserID: The name of the user running the Creo Parametric to connect to. If this is null, match any user. If this is an empty string, assume the current user.
TextPath: The path under which the message and menu files are held. If no external messaging or menus are needed pass null.
TimeoutSec: The time, in seconds, to wait for Creo Parametric to respond to the connection request. Pass null to use the default connection timeout.

Returns:: Object representing the asynchronous connection.

static pfcAsyncConnection_ptr ConnectWS (optional xrstring Display, optional xrstring UserID, optional xrstring WSName, optional xrstring TextPath, optional xint TimeoutSec)

Causes the application to connect to an existing Creo Parametric process and to an existing Pro/INTRALINK worksapce running on a host using a specified display. For use in simple and full asynchronous modes.

NOTE: This method is deprecated. Pro/INTRALINK 3.4 is not supported. Please use pfcAsyncConnection::Connect(optional xrstring, optional xrstring, optional xrstring, optional xint) to connect to an existing Creo Parametric process that has a Pro/INTRALINK 10.0 server registered.

If the method locates more than one Creo Parametric session with the appropriate characteristics, it will throw an pfcXToolkitAmbiguous exception.

If you want to connect or reconnect to a specific Creo Parametric session, use the method pfcAsyncConnection::ConnectById(pfcConnectionId_ptr, optional xrstring, optional xint)

The application may only connect to one Creo Parametric session at any time.

Parameters:

Display: The name of the display Creo Parametric is using. If this is null, match any display. If this is an empty string, assume the local host.
UserID: The name of the user running the Creo Parametric to connect to. If this is NULL, match any user. If this is an empty string, assume the current user.
WSName: The name of the workspace Creo Parametric should use. If this is NULL, match any available workspace.
TextPath: The path under which the message and menu files are held. If no external messaging or menus are needed pass null.
TimeoutSec: The time, in seconds, to wait for Creo Parametric to respond to the connection request.

Returns:: Object representing the asynchronous connection.

static pfcAsyncConnection_ptr ConnectById (pfcConnectionId_ptr Id, optional xrstring TextPath, optional xint TimeoutSec)

Connects to a specific Creo Parametric session by passing the identification string.

The ID string for a given session can be obtained from pfcAsyncConnection::GetConnectionId().

The application may only connect to one Creo Parametric session at any time.

Manual References:: Asynchronous Mode: Connecting Via Connection ID

Parameters:

Id: The connection id string previously obtained for the Creo Parametric session you wish to connect to.
TextPath: The path under which the message and menu files are held. If no external messaging or menus are needed pass null.
TimeoutSec: The time, in seconds, to wait for Creo Parametric to respond to the connection request. Pass null to use the default timeout.

Returns:: Object representing the asynchronous connection.

static optional pfcAsyncConnection_ptr GetActiveConnection ()

Connection established between your application and Creo Parametric. If your application is connected with Creo Parametric, call this function to get the connection object.

Manual References:: Asynchronous Mode: Setting Up a Noninteractive Session, Asynchronous Mode: Setting Up a Noninteractive Session

Returns:: Object representing the asynchronous connection.

pfcSession_ptr GetSession ()

DEPRECATED: since Creo 4
SUCCESSOR(S): <reference 3 to unknown entity >

The handle to the session of Creo Parametric for the current active connection.

Manual References:: Asynchronous Mode: Getting the Session Object

void End ()

Terminates and disconnects from the current Creo Parametric process.

Manual References:: Asynchronous Mode: Starting and Stopping Creo Parametric, Selection: Interactive Selection

Returns:

void Disconnect (optional xint TimeoutSec)

Disconnects the application from the current Creo Parametric process. Creo Parametric will still be running after this call.

For J-Link only: In order to clear allocated Creo Parametric memory owned by the application, PTC recommends forcing garbage collection (using Java's System.gc()) before disconnecting from Creo Parametric.

Exceptions thrown (but not limited to):

pfcXToolkitUnsupported - Connection is not Obtained

<reference 4 to unknown entity pfcExceptions::XProeWasNotConnected> - Handle not initialized

Manual References:: Asynchronous Mode: Setting Up a Noninteractive Session

Parameters:

TimeoutSec: The time, in seconds, to wait for Creo Parametric to respond to the disconnect request.

Returns:

void WaitForEvents ()

Initiates an event loop which will call event processing periodically to handle events returned from Creo Parametric. Applicable only for full asynchronous applications which are not supposed to carry out any tasks while waiting for Creo Parametric events.

This function will not return until interrupted by pfcAsyncConnection::InterruptEventProcessing() or an error. No separate application processing is possible until that time, except within Creo Parametric event callbacks.

Manual References:: Asynchronous Mode: Full Asynchronous Mode, Asynchronous Mode: Full Asynchronous Mode

Returns:

void InterruptEventProcessing ()

Call this function from within a Creo Parametric callback function to halt a loop currently running in pfcAsyncConnection::WaitForEvents().

Manual References:: Asynchronous Mode: Full Asynchronous Mode, Asynchronous Mode: Full Asynchronous Mode

Returns:

pfcConnectionId_ptr GetConnectionId ()

Extracts the identification handle of the current Creo Parametric process.

Format of identification string is the following.

"host:H:address_version:A:address_type:T:rpcnum:R:rpcversion:V:netaddr:N"

where H - host name where Creo Parametric runs A - address version T - address type R - RPC number V - RPC version N - net address. The identification string can be used in subsequent attmepts to connect to this Creo Parametric session by this application or any other Creo Parametric TOOLKIT or PFC-based application.

Exceptions thrown (but not limited to):

pfcXToolkitUnsupported - Connection is not Obtained

Manual References:: Asynchronous Mode: Connecting Via Connection ID, Asynchronous Mode: Connecting Via Connection ID

Returns:: The connection identifier handle.

xbool IsRunning ()

Determines whether you are currently connected to an actively responding Creo Parametric session.

Manual References:: Asynchronous Mode: Connecting Via Connection ID

Returns:: true if communications with Creo Parametric are possible false otherwise.

xbool ExecuteAsyncJavaMethod (xrstring Class, xrstring Method, pfcArguments_ptr InputArguments, xrstring ClassForUnlock)

This is the "JOTK sandbox" to execute methods with full OTK Asynchronous Java access. Can be used only in Java language binding.

Before executing the supplied Java method, the sandbox checks that the application is unlocked. It performs no execution and returns false if this check fails, which may happen because either the application is not unlocked (and overriding developer licenses are not present), or the application jar was not found (for instance, due to a wrong ClassForUnlock argument).

Parameters:

Class: Method's class. Full class name including the package, in Java syntax.
Method: Method's name.
InputArguments: Method's input arguments.
ClassForUnlock: The class used for unlocking this Java application. Full class name including the package, in Java syntax.

Returns:: False if the check for unlocking failed.

void EventProcess ()

Enables your process to respond to listener calls from Creo Parametric. You must call this function within your control loop in order that your application will be able to respond to listener calls. Creo Parametric will be blocked until the application responds to a registered listener.

Exceptions thrown (but not limited to):

pfcXToolkitGeneralError - Creo Session has already terminated.

Manual References:: Asynchronous Mode: Full Asynchronous Mode, Asynchronous Mode: Full Asynchronous Mode

Returns: