3.5 Opening a session

Once a connection between an application and the XFS Manager has successfully been negotiated (via WFSStartUp), the application establishes a virtual session with a service provider by issuing a WFSOpen (or WFSAsyncOpen) request. Opens are directed towards “logical services” as defined in the WOSA/XFS configuration. A service handle (hService) is assigned to the session, and is used in all the calls to the service in the lifetime of the session.

Note that applications may optionally choose to explicitly manage the concept of “application identity” when they need to use interdependent compound devices (see Section 3.8.2). This is achieved by using the WFSCreateAppHandle function to get an application handle (hApp), which is unique within the system. This function can be called multiple times to obtain multiple unique handles. An application handle parameter is then used in the WFSOpen function, directing the service provider to bind the specified application handle to the session being initiated. This allows a single application process (potentially multi-threaded) to act as multiple applications to the WOSA/XFS subsystem, to allow effective use of interdependent compound devices. An example of a case in which this could be useful is an application using the Multiple Document Interface (MDI); the application could associate an application handle with each MDI child window. See Section 3.8.2 for additional discussion of the use of application handles with compound devices. Note that neither service nor application handles may be shared among two or more applications.

The actions performed by the XFS Manager on an open are as follows:

• Retrieves the configuration information defining the specified logical service, in order to determine the DLL name of the service provider. The logical service name is the key to the configuration information.

• Loads the DLL containing the requested service provider, if it is not already loaded.

• Performs pre-processing and translation as necessary, depending on whether the synchronous or asynchronous open API has been issued.

• Generates a unique service handle (hService) that identifies the session with the service provider that is being established, to be passed back to the application as a parameter.

• Calls the service provider's WFPOpen function, passing the parameters needed.

The service provider does the following:

• Performs version negotiation, using the parameters specifying the SPI version requested by the XFS Manager, and the service-specific interface version requested by the application.

• Retrieves the configuration information.

• Asynchronously establishes a session with the service specified in the configuration on the specified workstation, if necessary, relying on the transport facilities provided.

• Upon completion of the request, posts a completion message (WFS_OPEN_COMPLETE), which goes to the application for a WFSAsyncOpen call, and to the XFS Manager for a WFSOpen call.

Note that even if the service is locked by another application, the open function succeeds, as defined in Section 3.8, “Exclusive Service and Device Access.”

An application programmer has at least two obvious choices as to when to perform the WFSOpen (and the complementary WFSClose) of the services it utilizes:

• Open the services during application initialization, keep them open, and close them during application shutdown.

• Perform the open each time the service is required, utilize it, and immediately close it.

Each technique has its own advantages. For example, while the first example might provide better performance, the second might be easier to program. In any case, upon a successful completion of an open, the WOSA/XFS subsystem returns a service handle which must be used for all subsequent communication with the service.

Note that an application must perform an open for each logical service that it wishes to utilize, even if the services are of the same type. For example, if an application wishes to utilize two separate receipt printers, it must open two separate logical services.

Furthermore, an application may need to open multiple logical services, even when a set of devices are housed in a single device. For example, consider a compound printer which includes both a receipt and a journal printer. If the application requires access to both the receipt and journal printer functions, it must open both a receipt logical service and a journal logical service.