Registering Node Databases

Table of Contents

• What is a Database
• Register and Unregister a Database
• Final Code

Describes how to register a database that will store information about a node system and nodes.

What is a Database

The database is being stored as one or several .json files, allowing for the access and modification of the stored information with a common text editor. The database does store information similar to what has been stored in resource files in the classic API. Similarly to resource files, such a database has to be shipped with plugins that implement Nodes API. A database stores a DataDescriptionDefinition that represents the raw description of data attributes. See DataDescription Manual for more information.

Register and Unregister a Database

A database must be registered on the startup process of Cinema 4D and unregistered when Cinema 4D is shutting down. To simplify that registration process, the macro MAXON_INITIALIZATION can be used. See Initialization for more information on that. The macro accepts two delegates: the first one will be used to register the database and the second to free it. All databases must be registered with a globally unique string identifier. Other than plugin identifiers, this identifier is not curated by Maxon and can be arbitrarily chosen by the user. But due to the required uniqueness, it is recommended to choose a sufficiently complex identifier, as one might risk otherwise identifier collisions. This example utilizes the reverse domain name notation for constructing identifier, e.g., net.maxonexample.handbook.nodes.registereddatabase. It is recommended to also employ this notation as a developer; used as a starting point for such MAXON API domain space scheme can be the profile scheme suggestion located in plugin identifiers overview page on Plugin Café. Note that you have to be registered on Plugin Café in order to be able to see that page.

Inside the first delegate function, use maxon::DataDescriptionDefinitionDatabaseInterface::RegisterDatabaseWithUrl() to register the database. The path defined with that URL has to be an existing path, as otherwise attempts of storing information in that database with the resource editor will fail.

  // Get plugin location
  const maxon::Url& binaryUrl = maxon::g_maxon.GetUrl();
  // Get plugin folder
  maxon::Url pluginDir = binaryUrl.GetDirectory();
  // Get resource folder (this folder must exist)
  const maxon::Url resourceUrl = pluginDir.Append("res"_s).Append("nodes"_s) iferr_return;
  // Register database
  maxon::DataDescriptionDefinitionDatabaseInterface::RegisterDatabaseWithUrl(g_nodeRendererDatabaseID, resourceUrl) iferr_return;

Use maxon::DataDescriptionDefinitionDatabaseInterface::UnregisterDatabase in the delegate function to unregister the database when cinema4D shutdown.

Final Code

The final code for registering a database for a plugin could look like this.

#include "maxon/datadescriptiondefinitiondatabase.h"
#include "maxon/module.h"
#include "maxon/previewimageprovider.h"
#include "maxon/datadescription_nodes.h"
 
 
 
static maxon::Result<void> ConfigurePreviewImageRequest(maxon::DataDictionaryObjectRef request)
{
  iferr_scope;
 
  request.Set(maxon::nodes::PREVIEWIMAGEREQUEST::PROVIDER, PreviewImageProviderExampleHandbook::GetClass()) iferr_return;
  return maxon::OK;
}
 
 
MAXON_METHOD maxon::Result<void> NodeRendererNodeSpaceImpl::Init(maxon::DataDictionary spaceData)
{
  iferr_scope;
  _class = NodeRendererNodeSystemClassImpl::GetClass().Create() iferr_return;
  spaceData.Set(maxon::nodes::NODESPACE::NODESYSTEMCLASS, _class) iferr_return;
 
  super.Init(spaceData) iferr_return;
  return maxon::OK;
}
 
 
static maxon::Id g_nodeRendererDatabaseID = maxon::Id("net.maxonexample.handbook.nodes.registereddatabase");
 
static maxon::Result<void> LoadResources()
{
  iferr_scope_handler
  {
    err.CritStop();
    return err;
  };
  // Get plugin location
  const maxon::Url& binaryUrl = maxon::g_maxon.GetUrl();
  // Get plugin folder
  maxon::Url pluginDir = binaryUrl.GetDirectory();
  // Get resource folder (this folder must exist)
  const maxon::Url resourceUrl = pluginDir.Append("res"_s).Append("nodes"_s) iferr_return;
  // Register database
  maxon::DataDescriptionDefinitionDatabaseInterface::RegisterDatabaseWithUrl(g_nodeRendererDatabaseID, resourceUrl) iferr_return;
  
  return maxon::OK;
}
 
static void FreeResources()
{
  iferr_scope_handler
  {
    err.CritStop();
    return;
  };
  // Unregister a database
  maxon::DataDescriptionDefinitionDatabaseInterface::UnregisterDatabase(g_nodeRendererDatabaseID) iferr_return;
}
MAXON_INITIALIZATION(LoadResources, FreeResources);