Skip to content

Latest commit

 

History

History
215 lines (141 loc) · 9.38 KB

dataservice-write-example.md

File metadata and controls

215 lines (141 loc) · 9.38 KB

Write example

On this page, find instructions on how to build and run the write example project on different platforms and publish data to a stream layer using HERE Data SDK for C++.

Before you run the example project, authorize to the HERE platform:

  1. On the Apps & keys page, copy your application access key ID and access key secret.

    For instructions on how to get the access key ID and access key secret, see Register your application section in the Identity & Access Management Developer Guide.

  2. In examples/main.cpp, replace the placeholders with your access key ID, access key secret, Here Resource Name (HRN) of the catalog, and name of the layer to which you want to publish data.

    Note

    You can also specify these values using the command line options.

    AccessKey access_key{};  // Your access key ID and access key secret.
std::string catalog;   // The HRN of the catalog to which you want to publish data.
std::string layer_id;  // The ID of the layer inside the catalog to which you want to publish data.

Build and run on Linux

To build and run the example project on Linux:

  1. Enable examples of the CMake targets.

    mkdir build && cd build
cmake -DOLP_SDK_BUILD_EXAMPLES=ON ..

  2. In the build folder, build the example project.

    cmake --build . --target dataservice-example

  3. Execute the example project.

    ./examples/dataservice-example --example write --key_id "here.access.key.id" --key_secret "here.access.key.secret" --catalog "catalog" --layer_id "layer_id"

  4. (Optional) To run the example with other parameters, run the help command, and then select the needed parameter.

    ./examples/dataservice-example --help

After building and running the example project, the following message displays automatically: "Publish Successful - TraceID: <TraceId generated by the platform>".

Build and run on Android

To integrate the Data SDK libraries in the Android example project:

Prerequisites for Android

  1. Set up the Android environment.
  2. In examples/android/app/src/main/cpp/MainActivityNative.cpp.in, replace the placeholders with your application access key ID, access key secret, catalog HRN, and layer name and specify that the example should run RunExampleWrite.

Note

To learn how to get the access key ID and access key secret, see the Register your application section in the Identity & Access Management Developer Guide.

Build the Data SDK on Android

  1. Set OLP_SDK_BUILD_EXAMPLES to ON.

  2. Specify the path to the Android NDK toolchain file using the CMAKE_TOOLCHAIN_FILE variable.

  3. If you want to build the SDK for a specific Android platform, use the -DANDROID_PLATFORM CMake flag, and if you want to build the SDK for a specific Android architecture, use the -DANDROID_ABI flag. For more details, see NDK-specific CMake variables.

    mkdir build && cd build
cmake .. -DOLP_SDK_BUILD_EXAMPLES=ON -DCMAKE_TOOLCHAIN_FILE=$NDK_ROOT/build/cmake/android.toolchain.cmake -DANDROID_ABI=arm64-v8a

    The CMake command generates a Gradle project in the build/examples/android folder.

  4. Install the Data SDK libraries into the sysroot directory.

    # If necessary, execute as sudo.
(sudo) make install

Build and run the APK

  1. In the Android Studio IDE, open the build/examples/android/build.gradle script.
  2. Provide your application access key ID, access key secret, catalog HRN, and layer name.
  3. Install and run the dataservice_example APK.

The main screen displays the following message: "Example has finished successfully".

Build and run on iOS

To integrate the Data SDK libraries in the iOS example application written in the Objective-C language:

Prerequisites for iOS

  1. To set up the iOS development environment, install the Xcode and command-line tools.

  2. Install external dependencies.

    For information on dependencies and installation instructions, see the related section in the README.md file.

  3. In examples/ios/ViewController.mm, replace the placeholders with your application access key ID, access key secret, catalog HRN, and layer name and specify that the example should run RunExampleWrite.

Note

To learn how to get the access key ID and access key secret, see the Register your application section in the Identity & Access Management Developer Guide.

mkdir build && cd build
cmake .. -GXcode  -DCMAKE_TOOLCHAIN_FILE=../cmake/toolchains/iOS.cmake -DPLATFORM=iphoneos -DOLP_SDK_BUILD_EXAMPLES=ON -DOLP_SDK_ENABLE_TESTING=OFF

To configure the Data SDK for a simulator, set the SIMULATOR variable to ON.

Build the Data SDK on iOS

  1. Set OLP_SDK_BUILD_EXAMPLES to ON.

  2. (Optional) To disable tests, set OLP_SDK_ENABLE_TESTING to OFF.

  3. Specify the path to the iOS toolchain file using the CMAKE_TOOLCHAIN_FILE variable.

    Note

    The iOS toolchain file is shipped together with the SDK and located under the <olp-sdk-root>/cmake/toolchains/iOS.cmake.

mkdir build && cd build
cmake .. -GXcode  -DCMAKE_TOOLCHAIN_FILE=../cmake/toolchains/iOS.cmake -DPLATFORM=iphoneos -DOLP_SDK_BUILD_EXAMPLES=ON -DOLP_SDK_ENABLE_TESTING=OFF

Build and run the application

  1. Open the generated Xcode project.

    open olp-cpp-sdk.xcodeproj

  2. In the Xcode project, from the list of schemes, select the dataservice-example scheme.

  3. In the dataservice-example target, specify your application access key ID and access key secret.

  4. Build and run the example application.

The main UI screen displays the following message: "Example has finished successfully". For more details, check the device logs.

If you encounter an error message, for a detailed error description, check the device logs. Example of an error message: "Example failed!".

How it works

Publish data to a stream layer

You can create a queue that streams data to data consumers in real time using a stream layer.

To publish data to the stream layer:

  1. Create the OlpClientSettings object.

    For instructions, see Create platform client settings.

  2. Create the StreamLayerClientSettings object.

    auto stream_client_settings = olp::dataservice::write::StreamLayerClientSettings{};

  3. Create the StreamLayerClient object with the HERE Resource Name (HRN) of the catalog that contains the layer, the stream layer client settings from step 2, and the platform client settings from step 1.

    auto client = olp::dataservice::write::StreamLayerClient(
olp::client::HRN{kCatalogHRN}, stream_client_settings, client_settings);

  4. Create the PublishDataRequest object with the data that you want to publish and layer ID.

    auto request = PublishDataRequest().WithData(buffer).WithLayerId(kLayer);

  5. Call the PublishData method with the DataRequest parameter.

    auto futureResponse = client.PublishData(request);

  6. Wait for the PublishDataResponse future.

    auto response = futureResponse.GetFuture().get();

The PublishDataResponse object holds details of the completed operation and is used to determine operation success and access resultant data:

  • IsSuccessful() – if the operation is successful, returns true. Otherwise, returns false.
  • GetResult() – if the operation is successful, returns the following resultant data: olp::dataservice::write::PublishDataResult
  • GetError() – contains error information as a result of an error in the olp::client::ApiError object.
if (response.IsSuccessful()) {
    auto response_result = response.GetResult();
    // Handle success
} else {
    auto api_error = response.GetError();
    // Handle fail
}