DriverSession::Handle

Returns the IVI session handle associated with the DriverSession-derived object.

When a client program invokes the driver's init or InitWithOptions function, an instance of the driver's DriverSession-derived class is created. This class is maintained in the driver project's DriverSession.h file. This instance is associated with an IVI session handle via the standard IVI function IviSession_New. The IviSession_New function is part of the IVI Shared Component and is used to store and retrieve IVI driver session state information in a standard and thread-safe fashion.

Nimbus IVI-C drivers use the standard IviSession_New function to create an IVI session and associate the driver's DriverSession object with that IVI session. When the IVI session is created, the IviSession_New function returns a ViSession handle that must be used in all subsequent function calls on that IVI session. Every IVI-C driver function (other than init and InitWithOptions) accepts of ViSession parameter that is used to retrieve the DriverSession object via the GetDriverSession function.

While global functions, such as typical IVI-C driver functions and attributes, accept a ViSession parameter from which the DriverSession object can be retrieved, functions defined on the DriverSession class itself do not accept a ViSession parameter. These functions are already defined on the DriverSession instance, so they need only access the IVI session handle member variable that was stored on the DriverSession instance when it was created. The Handle function provides access to that member variable.

The following code demonstrates how to override the Handle function:

// DriverSession.h
class Acme4321DriverSession : public DriverSession
{
public:
    Acme4321DriverSession(ViSession handle)
        : DriverSession(handle, 2000, 2000, 2000, false, 1000)
    {
    }

    void MyHelper()
    {
        auto iviSession = Handle();

        // ...
    }
};