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:
- Create an
AuthenticationCredentials
instance. - Create an
AuthenticationSettings
instance. - 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:
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 createdAuthenticationSettings
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:
-
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.
-
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
.
-
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.
-
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:
-
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" );
}
-
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.