Plugin Licensing Manual

Table of Contents

• About
• Plugin Licensing Workflow
• Cinema 4D License Entitlements
• Cinema 4D License Report structure
• Cinema 4D License Provisioning
• New API functions
• Further Reading

About

This manual contains information with regard to the new Cinema 4D R21 licensing functions that have been introduced to substitute the previous classes / methods available in earlier versions.

More specifically the following class has been removed in Cinema 4D R21:

• GeGetSerialInfo();
• SerialInfo;
• SNHookClass.

In Cinema 4D R21 the following functions have been introduced and are detailed later on:

• GetGeneralLicensingInformation() (defined in c4d_general.h);
• ExportLicenses() (defined in c4d_general.h).
• GeGetUserName() (defined in c4d_general.h)

It must be noted that the new mechanism is not replacing the old one and doesn't grant the same level of functionality.

It has been designed to grant:

• plugin vendors retrieving information about Cinema 4D license in order to hook their licenses to this data;
• plugins to load plugin licenses (either locally or online) and to compare values stored in the license with the values retrieve from the running instance of Cinema.

It has NOT been designed to grant:

• plugin licenses being provisioned in a LAN environment by either the new MAXON License Server or the RLM Server.

Plugin Licensing Workflow

With Cinema 4D R21 a new licensing workflow has been envisioned for plugin vendors willing to license their product for Cinema 4D.

The basic workflow can be streamlined as:

1. the new Customer buys a plugin from Vendor;
2. the Vendor asks Customer to provide him with one or more Cinema 4D license reports;
3. the Vendor receives the report(s) and generates one or more plugin license(s);
4. the plugin licenses are provided to the Customer together with the link to download the plugin and are copied by Customer in the folder searched by the plugin.

A slightly more automated scenario (which is the one adopted in the example below) could be:

1. the new Customer buys and downloads the plugin from Vendor;
2. the Customer installs the plugin and run Cinema 4D;
3. at Cinema 4D start, if no valid plugin license is found, the plugin asks the Customer via a question dialog if a C4D License Report should be automatically generated;
4. the Customer retrieves the generated file and provide it to the Vendor;
5. the Vendor receives the report(s) and generates one or more plugin license(s);
6. the plugin licenses are provided to the Customer and are copied by Customer in the folder searched by the plugin;
7. at next Cinema 4D start, the plugin license finds, in the searched path(s), the valid license.

Both described scenarios don't rely on any online activation mechanism but extending them to grant this functionality shouldn't be too hard. With regard to this a potential workflow might be:

1. the new Customer buys and download the plugin from Vendor;
2. the Customer installs the plugin and run Cinema 4D;
3. at Cinema 4D start, if no valid plugin license is retrieved by on-line querying the Vendor Licensing System, the plugin asks the Customer via a question dialog if a Cinema 4D License Report should be send to the Vendor;
4. the Vendor automatically receive and process the report(s) based on their sales records and generates one or more plugin license(s) which are then stored in the Vendor Licensing System;
5. at next Cinema 4D start, the plugin license retrieves, by querying on-line Vendor Licensing System, a valid license.

Note

A plugin can be bound to a userID, a systemID or both. Studios with multiple uses may use a shared userID. See Release 21 FAQ.

Cinema 4D License Entitlements

With Cinema 4D R21, each configuration is connected to a specific product identifier, where the identifier follows the scheme net.maxon.license.app.{X}{Y}{Z}. The placeholders X, Y, and Z can take the following values:

• X: "cinema4d-release", "teamrender-release" or "forger"
• Y: "~commercial", "~education", "~lite", "~nfr", "~trial", "~student" or "~commandline",
• Z: not set or "-floating".

Commonly encountered product identifier combinations are:

• net.maxon.license.app.cinema4d-release~commandline: C4D (release binary) running in command-line mode with license provided by the global MAXON Provisioning Infrastructure (id.maxon.net);
• net.maxon.license.app.cinema4d-release~commandline-floating: C4D (release binary) running in command-line mode with a license provided either by MAXON License Server or RLM Server ;
• net.maxon.license.app.cinema4d-release~commercial: C4D (release binary) running in standard mode with license provided by the global MAXON Provisioning Infrastructure (id.maxon.net);
• net.maxon.license.app.cinema4d-release~commercial-floating: C4D (release binary) running in standard mode with a license provided either by MAXON License Server or RLM Server ;
• net.maxon.license.app.cinema4d-release~education: C4D (release binary) running in educational mode with license provided by the global MAXON Provisioning Infrastructure (id.maxon.net);
• net.maxon.license.app.cinema4d-release~education-floating: C4D (release binary) running in educational mode with a license provided either by MAXON License Server or RLM Server ;
• net.maxon.license.app.cinema4d-release~trial: C4D (release binary) running in Trial mode with license provided by the global MAXON Provisioning Infrastructure (id.maxon.net);
• net.maxon.license.app.teamrender-release~commercial: TeamRender Server (release binary) running in standard mode with license provided by the global MAXON Provisioning Infrastructure (id.maxon.net);
• net.maxon.license.app.teamrender-release~commercial-floating: TeamRender Server (release binary) running in standard mode with license provided by MAXON License Server or RLM Server ;
• net.maxon.license.app.teamrender-release~education: TeamRender Server (release binary) running in educational mode with license provided by the global MAXON Provisioning Infrastructure (id.maxon.net);
• net.maxon.license.app.teamrender-release~education-floating: TeamRender Server (release binary) running in educational mode with license provided by MAXON License Server or RLM Server ;
• net.maxon.license.app.teamrender-release~trial: TeamRender Server (release binary) running in Trial mode with license provided by the global MAXON Provisioning Infrastructure (id.maxon.net);

Note

The command-line version can also be run with the regular commercial license. During that consumption no C4D can be launched in parallel though.

Cinema 4D License Report structure

With the new Cinema 4D R21 API Licensing calls, it possible to generate a report of Cinema 4D license data to be used by plugin vendors to generate their plugin licenses against to. The data stored in the report can be disclosed to plugin vendors since no sensitive data or license keys are part of the report

A typical report, is a JSON-structured container and looks like:

{
    "userid":"AAAAAAAA-BBBB-CCCC-DDDD-EEEEEEEEEEEE",
    "systemid":"01234567890",
    "name":"A name",
    "surname":"A surname",
    "version":"21.022"
    "currentproduct":"net.maxon.license.app.cinema4d-release~commercial",
    "accountlicenses":{
      "net.maxon.license.app.cinema4d-release~commandline-floating":10,
      "net.maxon.license.app.teamrender-release~commercial-floating":10,
      "net.maxon.license.app.cinema4d-release~commercial-floating":10,
      "net.maxon.license.app.cinema4d-release~education-floating":10,
      "net.maxon.license.app.teamrender-release~education-floating":10,
      "net.maxon.license.app.teamrender-release~commercial":5,
      "net.maxon.license.app.cinema4d-release~commercial":5
    }
}

A few notes:

• the userid is a unique identifier directly bound to the user account used to login in id.maxon.net;
• the systemid is a unique identifier directly bound to the hardware used when the license report was generated; the id stays constant as long as potential changes to hardware configuration are limited;
• the name is the Customer name bound to the user ID;
• the surname is the Customer surname bound to the user ID;
• the version is the Cinema 4D version that was running when the report was generated;
• the currentproduct is the Cinema 4D product configuration that was running when the report was generated;
• the accountlicenses is a dictionary containing the different Cinema 4D product configurations owned by the user ID and their quantity.

Note

The accountlicenses is optional and only present if Cinema 4D is running with valid account logged-in.

The report can be conveniently managed by using the maxon::JsonParserInterface class.

Considering the structure of the report, if a plugin needs to be deployed in a render-farm or on multiple machines, it's likely the Customer to provide the plugin Vendor with as many reports as the number of machines supposed to use the plugin.

At the same time it's on the plugin Vendor to eventually generate a license which can be validate independently of the system ID or independently of the user ID or independently on the product ID.

These considerations are left to the plugin vendor designing his own licensing scheme.

Cinema 4D License Provisioning

Due to the renewed business model, Cinema 4D R21 doesn't rely anymore on serial numbers for validating the license but rather introduces a new authentication mechanism based on account-related online activation.

Because of this new approach, Cinema 4D can be provided with a valid licenses by:

1. the global Maxon Licensing infrastructure by authenticating via the given credentials;
2. the new Maxon License Server by authenticating via the local credentials stored on the server;
3. the RLM Server.

New API functions

Cinema 4D R21 introduce the following global functions to query Cinema 4D about its licensing status, to programmatically generated Cinema 4D License Report or to check for a specific feature.

• GetGeneralLicensingInformation(): Returns information on the currently-running license. The currently-running license is the product configuration of Cinema 4D found at the call-time of the function (available in Python);

      // allocate three maxon::String to store user-, system- and product-IDs
      maxon::String userID, systemID, productID, licenseID, userName;
   
      // query Cinema for the values in use in the current session
      GetGeneralLicensingInformation(productID, systemID, userID, licenseID, userName) iferr_return;
   
      // print the IDs
      DiagnosticOutput("UserID:\t\t@", userID);
      DiagnosticOutput("SystemID:\t@", systemID);
      DiagnosticOutput("ProductID:\t@", productID);
   

• ExportLicenses(): returns a maxon::String containing the Cinema 4D License Report. It can be parsed by a JSONParser to retrieve a maxon::DataDictionary filled with the data contained in the returned maxon::String (available in Python);

      // allocate a maxon::String to store the license report output
      const maxon::String c4dLicenseReport = ExportLicenses() iferr_return;
      
      const maxon::Url c4dLicenseReportUrl(c4dLicenseReport);
      const maxon::InputStreamRef c4dLicenseStreamRef = c4dLicenseReportUrl.OpenInputStream() iferr_return;
   
      // check passed argument
      if (c4dLicenseReport.IsEmpty())
        return maxon::UnexpectedError(MAXON_SOURCE_LOCATION, "C4D License report is empty."_s);
   
      // create a JSONParser reference
      
      const maxon::ParserRef jsonParser = maxon::ParserClasses::JsonParser().Create() iferr_return;
   
      // allocate a SingleValueReceiver to store the data read from the JSONParser;
      maxon::SingleValueReceiver<const maxon::DataDictionary&> readData;
   
      // parse the string  and check it's containing a valid JSON structure
      jsonParser.Read(c4dLicenseStreamRef, maxon::PARSERFLAGS::NONE, maxon::GetUtf8DefaultDecoder(), readData) iferr_return;
      
   
      // return the data in the form of a maxon::DataDictionary
      const maxon::DataDictionary licenseDict = readData.Get().GetValue() iferr_return;
   
      // print the retrieved C4D License DataDictionary
      DiagnosticOutput("-- Cinema 4D License Report DataDictionary --\n@", licenseDict);

• CheckLicenseFeature(): queries Cinema 4D with regard to certain license features (not available on Python).

      // allocate a maxon::InternedId instance
      maxon::InternedId internedID;
   
      // init to the product ID string (e.g. net.maxon.license.app.cinema4d-release~commercial)
      internedID.Init(productID) iferr_return;
   
      // check if product/feature is allowed
      const maxon::Bool isProductAllowed = CheckLicenseFeature(internedID);
   
      if (isProductAllowed)
        DiagnosticOutput("ProductID [@] is allowed", productID);
      else
        DiagnosticOutput("ProductID [@] is not allowed", productID);
   

Further Reading

• Maxon API Files & Media
• NetworkWebServerInterface Manual
• Stream Conversions Manual
• AES Manual