Add catalog to DataStoreServer and DataStoreClient instances

When the DataStoreServer and DataStoreClient instances are created, add an OCM catalog to them.

Before you add the catalog, do the following:

1. Create an AuthenticationCredentials instance.
2. Create an AuthenticationSettings instance.
3. Create a CatalogSettings instance.

Create an AuthenticationCredentials instance

To access data from the OCM catalog, create an AuthenticationCredentials instance using the here.access.key.іd and here.access.key.secret values from your platform credentials.

For instructions on how to get platform credentials, see the "Get credentials section" in the Getting Started Guide.

Example:

#include <olp/authentication/AuthenticationCredentials.h>
...
olp::authentication::AuthenticationCredentials credentials(
    "your-here-access-key-id", "your-here-access-key-secret" );

In the example above, "your-here-access-key-id" and "your-here-access-key-secret" are the here.access.key.іd and here.access.key.secret values from your platform credentials, respectively.

Read authentication credentials from a file

To create an AuthenticationCredentials instance, you can also specify the path to the file with credentials downloaded from the HERE platform.

For instructions on how to get platform credentials, see the "Get credentials section" in the Getting Started Guide.

Example:

boost::optional< olp::authentication::AuthenticationCredentials > credentials
    = olp::authentication::AuthenticationCredentials::ReadFromFile(
        "path-to-credentials-file" );

In the example above, "path-to-credentials-file" is the path to the file with credentials downloaded from the HERE platform.

If an error occurs, ReadFromFile returns boost::none.

Create an AuthenticationSettings instance

Сreate an AuthenticationSettings instance using the previously created AuthenticationCredentials, Network and TaskScheduler instances.

Note: If you do not define the TaskScheduler explicitly or set the number of threads to 1, HERE Data SDK for C++ will handle all authentication requests synchronously.

Example:

#include <olp/authentication/TokenProvider.h>
#include <olp/clientmap/datastore/Settings.h>
...
olp::authentication::Settings settings( credentials );
settings.network_request_handler = network;
settings.task_scheduler = task_scheduler;

olp::client::AuthenticationSettings authentication_settings;
authentication_settings.provider
    = olp::authentication::TokenProviderDefault( std::move( settings ) );

In the example above, the following objects are used:

• credentials – the previously created AuthenticationCredentials instance.
• network – the previously created Network instance.
• task_scheduler – the previously created TaskScheduler instance.

Create a CatalogSettings instance

Create a CatalogSettings instance using the previously created AuthenticationSettings instance.

Example:

#include <olp/clientmap/datastore/Settings.h>
...
olp::clientmap::datastore::CatalogSettings catalog_settings;
catalog_settings.authentication_settings = authentication_settings;

In the example above, authentication_settings is the previously created AuthenticationSettings instance.

Set a catalog version

You can configure DataStoreClient to get data from a specific version of the OCM catalog.

Notes:

• You cannot add two versions of same catalog to the same DataStoreClient instance for map data consistency reasons. For more information, refer to Map data consistency.

• To get data from different versions of the same catalog, create a DataStoreClient instance for each catalog version and add different versions of the catalog to different DataStoreClient instances.

Example:

catalog_settings.version = 8;

If you do not set version explicitly or set it to boost::none, the catalog version is set internally to the latest version that is available on the HERE platform when the catalog is added.

Add a catalog

To add a catalog and access its data:

1. Add a catalog to the DataStoreServer instance using the HERE Resource Name (HRN) of the catalog and the previously created CatalogSettings instance.

    const auto add_catalog_server =
        server->AddCatalog( "catalog-hrn", catalog_settings );
   

   In the example above, the following objects and parameters are used:

   • "catalog-hrn" – the HRN of the catalog.
   • catalog_settings – the previously created CatalogSettings instance.

2. Check if the AddCatalog operation is successful.

    if ( !add_catalog_server.IsSuccessful( ) )
    {
        OLP_SDK_LOG_WARNING_F( kLogTag, "Failed to add a catalog to server - error=%s",
                               ToString( add_catalog_server.GetError( ) ).c_str( ) );
        return EXIT_SUCCESS;
    }
   

   The operation can be unsuccessful if one of the following is true:

   • The catalog with the requested HRN does not exist.
   • DataStoreClient fails to check if the catalog with the requested HRN exists. Catalog existence is checked only if the catalog version is not set or set to boost::none.

3. If the AddCatalog operation is successful for the DataStoreServer instance, to work with the current catalog, save the CatalogHandle.

    const auto server_catalog_handle = add_catalog_server.GetResult( );
   

   You can use the received catalog handle only to work with the catalog added to the current DataStoreServer instance.

4. Add the catalog to the DataStoreClient instance using the HRN of the catalog and the previously created CatalogSettings instance.

   Example:

    const auto add_catalog_client =
        client.AddCatalog( "catalog-hrn", catalog_settings );
   

   In the example above, the following objects and parameters are used:

   • client – the previously created DataStoreClient instance.
   • "catalog-hrn" – the HRN of the catalog.
   • catalog_settings – the previously created CatalogSettings instance.

5. Check if the AddCatalog operation is successful.

   Note: The operation can be unsuccessful because of the reasons specified in step 2.

   Example:

    if ( !add_catalog_client.IsSuccessful( ) )
    {
        LOG_ERROR( "Failed to add the catalog" );
    }
   

6. If the AddCatalog operation is successful for the DataStoreClient instance, to access data from the added catalog, save the CatalogHandle.

   Example:

    const auto client_catalog_handle = add_catalog_client.GetResult( );
   

   You can use the received catalog handle only to work with data added to the current DataStoreClient instance.