C++ adapter

This article describes setting up and using the OpenFin adapter for C++.

Set up

1. Download the latest x64 or x86 version of the OpenFin C++ adapter package, depending on the architecture that your application is built for. The package contains two application extension (.dll) files, an object library (.lib) file, and a header (.h) file.

2. Copy the .lib file into an appropriate folder within your project structure (for example, a lib subfolder).

3. Copy the .dll files into the run folder of your application so that they can be loaded at runtime.

4. Copy the .h file into an appropriate folder (for example, alongside your other source files, or in a separate headers folder).

5. In your IDE, modify the linker properties of your project to add the .lib file. For example, in Microsoft Visual Studio, this setting is under Configuration Properties > Linker > Input > Additional Dependencies.

6. If necessary, add the folder where you saved the .lib file. For example, in Visual Studio, modify the property Additional Library Directories, under Linker > General.

You can then include the OpenFinAdapter.h file in your source file:

#include "OpenFinAdapter.h"

To use the adapter in your code, create an instance of RuntimeOptions. For example:

auto runtimeOptions = OpenFinAdapterApi::RuntimeOptions(
  "my-cpp-application",
  "OPENFIN_LICENSE_KEY",
  "RUNTIME_VERSION_STRING");

This constructor uses the most common defaults and works well for most cases. There is an alternative constructor available with more parameters for greater customizability, if necessary. Refer to the C++ adapter API reference for details.

How to use the Channels API

OpenFin’s Channels API provides fine-grained control over messaging. You can create channels, and clients of those channels. Each channel can register a list of commands or actions that the channel provider handles.

Get an instance of the OpenFin runtime. Create an instance with the runtimeOptions instance you created when you set up:

auto factory = OpenFinAdapterApi::RuntimeFactory();
auto runtime = factory.getRuntimeInstance(runtimeOptions);

Establish a connection:

runtime->connectAsync().get();

The connectAsync() function is asynchronous, returning a std::future object.
The call to .get() ensures that it waits synchronously for the connection to complete.
Other adapter functions in this example work similarly.

Create a channel called “MyAppActions”:

auto channel = runtime->getChannels()->createProvider("MyAppActions");

Create and register an event handler for the channel

Declare a helloHandler function for handling SayHello actions:

shared_ptr<string> helloHandler(const shared_ptr<string>& message, const OpenFinAdapterApi::EndpointId& endpoint)
{
    // First remove the quotes from the incoming message
    auto response = "\"Hello, " + message->substr(1, message->length() - 2) + "\"";
    return make_shared<string>(response);
}

The adapter requires all message payloads and responses to be valid JSON. In this example, the messages are simple JSON strings, so they need to be enclosed in quotation marks (").
Register the "SayHello" topic with the provider, passing the handler function to it. Then open the channel:

channel->registerTopic("SayHello", helloHandler);
channel->openAsync().get();

Create a client

Create a client of the channel you created:

auto clientRuntimeOptions = OpenFinAdapterApi::RuntimeOptions(
  "my-cpp-application-client",
  "OPENFIN_LICENSE_KEY",
  "RUNTIME_VERSION_STRING");

auto clientRuntime = factory.getRuntimeInstance(clientRuntimeOptions);

auto client = clientRuntime->getChannels()->createClient("MyAppActions");
client->connectAsync().get();

The adapter does not support channel messaging where both ends of the channel were created by the same runtime object. In most real-world use cases, messaging is between separate applications, so this restriction does not pose a problem. However, this example, with a single application, creates another runtime object for the client to use. The two runtime objects must have different UUIDs.

Send messages

Send messages between the two runtime objects:

auto result = client->dispatchAsync("SayHello", "\"Your name goes here\"").get();
std::cout << "Responded with " << *result << "\n";

Results:

• A message is returned.

• Responded with “Hello, Your name goes here” is written to the console.

Clean up

Disconnect from the runtime after all calls to the channels API complete:

runtime->disconnectAsync().get();
clientRuntime->disconnectAsync().get();

License

Provide your license key as the second parameter of the OpenFinAdapterApi::RuntimeOptions constructor when creating the runtime. If you do not have license key, please contact us for one.