Engage Engine API  1.246.9086
Loading...
Searching...
No Matches
EngageInterface.h File Reference

API functions, codes, and more. More...

#include <stdint.h>
#include "EngageConstants.h"

Go to the source code of this file.

Classes

struct  _EngageEvents_t
 Event Handlers Struct. More...
 

Macros

#define ENGAGE_API   __attribute__ ((visibility ("default")))
 
#define _Nullable
 
#define _Nonnull
 

Typedefs

typedef void(* PFN_ENGAGE_LOG_HOOK) (int level, const char *_Nonnull tag, const char *_Nonnull message)
 Prototype for logging callbacks.
 
typedef void(* PFN_ENGAGE_HIGH_RES_TIMER_TICK) (uint32_t tickType, uint64_t ticksSoFar)
 Prototype for the high-resolution timer callback.
 
typedef struct _EngageEvents_t EngageEvents_t
 Event Handlers Struct.
 

Functions

ENGAGE_API int engageSetLogLevel (int level)
 [SYNC] Sets the Engine's logging level.
 
ENGAGE_API int engageSetLogTagExtension (const char *_Nullable tagExtension)
 [SYNC] Sets the Engine's log tag extension.
 
ENGAGE_API int engageSetLoggingOutputOverride (const _Nullable PFN_ENGAGE_LOG_HOOK pfnHook)
 [SYNC] Sets/clears the output override callback for log messages.
 
ENGAGE_API int engageEnableSyslog (int enable)
 [SYNC] Enables or disables logging to syslog.
 
ENGAGE_API int engageRegisterEventCallbacks (const EngageEvents_t *_Nonnull pEvents)
 [SYNC] Registers application event handlers with the Engine
 
ENGAGE_API int engageInitialize (const char *_Nullable enginePolicyConfiguration, const char *_Nullable userIdentity, const char *_Nullable tempStoragePath)
 [SYNC] Initializes the Engine.
 
ENGAGE_API int engageShutdown ()
 [SYNC] Shuts down the Engine
 
ENGAGE_API int engageStart (void)
 [ASYNC] Starts the Engine
 
ENGAGE_API int engageStop (void)
 [ASYNC] Stops the Engine's internal processing
 
ENGAGE_API int engageCreateGroup (const char *_Nonnull jsonConfiguration)
 [ASYNC] Creates a group object
 
ENGAGE_API int engageDeleteGroup (const char *_Nonnull id)
 [ASYNC] Deletes a previously-created group object
 
ENGAGE_API int engageJoinGroup (const char *_Nonnull id)
 [ASYNC] Joins a group
 
ENGAGE_API int engageLeaveGroup (const char *_Nonnull id)
 [ASYNC] Leaves a group
 
ENGAGE_API int engageBeginGroupTx (const char *_Nonnull id, int txPriority, uint32_t txFlags)
 [ASYNC] Begin audio transmission on a group
 
ENGAGE_API int engageBeginGroupTxAdvanced (const char *_Nonnull id, const char *_Nonnull jsonParams)
 [ASYNC] Begin audio transmission on a group with additional parameters
 
ENGAGE_API int engageEndGroupTx (const char *_Nonnull id)
 [ASYNC] Ends transmission on an audio group
 
ENGAGE_API int engageSetGroupRxTag (const char *_Nonnull id, uint16_t tag)
 [ASYNC] Sets/clear a audio stream subchannel tag
 
ENGAGE_API int engageMuteGroupRx (const char *_Nonnull id)
 [ASYNC] Mutes play-out of received audio
 
ENGAGE_API int engageUnmuteGroupRx (const char *_Nonnull id)
 [ASYNC] Unmutes play-out of received audio
 
ENGAGE_API int engageMuteGroupTx (const char *_Nonnull id)
 [ASYNC] Mutes microphone audio capture
 
ENGAGE_API int engageUnmuteGroupTx (const char *_Nonnull id)
 [ASYNC] Unmutes microphone audio capture
 
ENGAGE_API int engageSetGroupRxVolume (const char *_Nonnull id, int left, int right)
 [ASYNC] Sets the audio play-out volume of the group
 
ENGAGE_API int engageSetGroupRules (const char *_Nonnull id, const char *_Nonnull jsonParams)
 [ASYNC] Sets the audio play-out volume of the group
 
ENGAGE_API int engageUpdatePresenceDescriptor (const char *_Nonnull id, const char *_Nonnull descriptorJson, int forceBeacon)
 [ASYNC] Updates the application-defined elements of a presence descriptor
 
ENGAGE_API int engageEncrypt (const uint8_t *_Nonnull src, size_t size, uint8_t *_Nonnull dst, const char *_Nonnull passwordHexByteString)
 [SYNC] Encrypt data using the Engine's cryptography module
 
ENGAGE_API int engageDecrypt (const uint8_t *_Nonnull src, size_t size, uint8_t *_Nonnull dst, const char *_Nonnull passwordHexByteString)
 [SYNC] Decrypt data using the Engine's cryptography module
 
ENGAGE_API const char *_Nonnull engageGetVersion ()
 [SYNC] Returns the version of the Engine
 
ENGAGE_API const char *_Nonnull engageGetActiveLicenseDescriptor ()
 [SYNC] Returns the currently-active license descriptor
 
ENGAGE_API const char *_Nonnull engageGetLicenseDescriptor (const char *_Nonnull entitlement, const char *_Nonnull key, const char *_Nullable activationCode, const char *_Nullable manufacturerId)
 [SYNC] Returns a license descriptor for the parameters passed in
 
ENGAGE_API int engageUpdateLicense (const char *_Nonnull entitlement, const char *_Nonnull key, const char *_Nullable activationCode, const char *_Nullable manufacturerId)
 [ASYNC] Update the active license with new parameters
 
ENGAGE_API int engageSendGroupRtp (const char *_Nonnull id, const uint8_t *_Nonnull payload, size_t size, const char *_Nonnull jsonParams)
 [ASYNC] Send an application-structured byte array to a group as a specialized RTP payload
 
ENGAGE_API int engageRegisterGroupRtpHandler (const char *_Nonnull id, uint16_t payloadId)
 [ASYNC] Registers the application as the handler for an RTP payload
 
ENGAGE_API int engageUnregisterGroupRtpHandler (const char *_Nonnull id, uint16_t payloadId)
 [ASYNC] Unregisters the application as the handler for an RTP payload
 
ENGAGE_API int engageSendGroupBlob (const char *_Nonnull id, const uint8_t *_Nonnull blob, size_t size, const char *_Nonnull jsonParams)
 [ASYNC] Send an application-structured byte array to a group as an Engine-managed blob
 
ENGAGE_API int engageSendGroupRaw (const char *_Nonnull id, const uint8_t *_Nonnull raw, size_t size, const char *_Nonnull jsonParams)
 [ASYNC] Send an application-structured byte array to a group with minimal Engine involvement
 
ENGAGE_API int engagePlatformServiceDiscovered (const char *_Nonnull id, const char *_Nonnull jsonParams)
 [ASYNC] Informs the Engine that the application has discovered a service
 
ENGAGE_API int engagePlatformServiceRediscovered (const char *_Nonnull id, const char *_Nonnull jsonParams)
 [ASYNC] Informs the Engine that the application has rediscovered a service
 
ENGAGE_API int engagePlatformServiceUndiscovered (const char *_Nonnull id)
 [ASYNC] Informs that Engine that a previously-discovered service has disappeared
 
ENGAGE_API int engageQueryGroupTimeline (const char *_Nonnull id, const char *_Nonnull jsonParams)
 [ASYNC] Requests that the Engine deliver a timeline report for the group
 
ENGAGE_API int engageQueryGroupHealth (const char *_Nonnull id)
 [ASYNC] Requests that the Engine deliver a health report for the group
 
ENGAGE_API int engageQueryGroupStats (const char *_Nonnull id)
 [ASYNC] Requests that the Engine deliver a statistics report for the group
 
ENGAGE_API int engageLogMsg (int level, const char *_Nonnull tag, const char *_Nonnull msg)
 [SYNC] Log a message via the Engine's logger
 
ENGAGE_API const char *_Nonnull engageGetNetworkInterfaceDevices ()
 [SYNC] Returns an array of network interface devices in JSON format
 
ENGAGE_API const char *_Nonnull engageGetAudioDevices ()
 [SYNC] Returns an array of audio device descriptor interface devices in JSON format
 
ENGAGE_API const char *_Nonnull engageGenerateMission (const char *_Nonnull keyPhrase, int audioGroupCount, const char *_Nullable rallypointHost, const char *_Nullable missionName)
 [SYNC] Generates a mission based on a key phrase
 
ENGAGE_API const char *_Nonnull engageGenerateMissionUsingCertStore (const char *_Nonnull keyPhrase, int audioGroupCount, const char *_Nullable rallypointHost, const char *_Nullable missionName, const char *_Nonnull certStoreFn, const char *_Nullable certStorePasswordHexByteString, const char *_Nullable certStoreElement)
 [SYNC] Generates a mission based on a key phrase and using a specified certificate store
 
ENGAGE_API int engageSetMissionId (const char *_Nullable missionId)
 [SYNC] Sets the (optional) mission ID for the Engine
 
ENGAGE_API int engageCreateCertStore (const char *_Nonnull fileName, const char *_Nullable passwordHexByteString)
 [SYNC] Creates a certificate store
 
ENGAGE_API int engageOpenCertStore (const char *_Nonnull fileName, const char *_Nullable passwordHexByteString)
 [SYNC] Opens a certificate store
 
ENGAGE_API const char *_Nonnull engageGetCertStoreDescriptor (void)
 [SYNC] Returns a JSON descriptor of the currently opened certificate store.
 
ENGAGE_API int engageCloseCertStore (void)
 [SYNC] Closes the current certificate store (if any)
 
ENGAGE_API int engageSetCertStoreCertificatePem (const char *_Nonnull id, const char *_Nonnull certificatePem, const char *_Nullable privateKeyPem, const char *_Nullable tags)
 [SYNC] Adds/updates a certificate and (optionally) private key using PEM strings
 
ENGAGE_API int engageSetCertStoreCertificateP12 (const char *_Nonnull id, uint8_t *_Nonnull data, size_t size, const char *_Nullable password, const char *_Nullable tags)
 [SYNC] Adds/updates a certificate and (optionally) private key using P12 content
 
ENGAGE_API int engageDeleteCertStoreCertificate (const char *_Nonnull id)
 [SYNC] Deletes a certificate and its private key (if any)
 
ENGAGE_API const char *_Nonnull engageGetCertStoreCertificatePem (const char *_Nonnull id)
 [SYNC] Returns a certificate in PEM format. The private key (if any) is NOT returned.
 
ENGAGE_API const char *_Nonnull engageGetCertificateDescriptorFromPem (const char *_Nonnull pem)
 [SYNC] Returns a JSON object describing the certificate PEM.
 
ENGAGE_API const char *_Nonnull engageGetArrayOfCertificateDescriptorsFromPem (const char *_Nonnull pem)
 [SYNC] Returns a JSON array, with each element being an object describing the certificate PEM.
 
ENGAGE_API int engageImportCertStoreElementFromCertStore (const char *_Nonnull id, const char *_Nonnull srcId, const char *_Nonnull srcFileName, const char *_Nonnull srcPasswordHexByteString, const char *_Nullable tags)
 [SYNC] Adds/updates an element (certificate and optionally private key) from another certificate store.
 
ENGAGE_API const char *_Nonnull engageQueryCertStoreContents (const char *_Nonnull fileName, const char *_Nullable passwordHexByteString)
 [SYNC] Returns an extended descriptor of named certificate store
 
ENGAGE_API int engageSetCertStoreCertificateTags (const char *_Nonnull id, const char *_Nullable tags)
 [SYNC] Updates a certificate's tags
 
ENGAGE_API int engageCreateBridge (const char *_Nonnull jsonConfiguration)
 [ASYNC] Creates a bridge object
 
ENGAGE_API int engageDeleteBridge (const char *_Nonnull id)
 [ASYNC] Deletes a bridge object
 
ENGAGE_API const char *_Nonnull engageGetHardwareReport ()
 [SYNC] Returns a hardware report
 
ENGAGE_API int engageAddGroupTimelineEvent (const char *_Nonnull id, const char *_Nonnull jsonParams, const uint8_t *_Nullable blobData, size_t blobSize)
 [ASYNC] Requests that the Engine add a timeline event
 
ENGAGE_API int engageUpdateGroupTimelineEvent (const char *_Nonnull id, const char *_Nonnull jsonParams, const uint8_t *_Nullable blobData, size_t blobSize)
 [ASYNC] Requests that the Engine update a timeline event
 
ENGAGE_API int engageDeleteGroupTimelineEvent (const char *_Nonnull id, const char *_Nonnull jsonParams)
 [ASYNC] Requests that the Engine delete timeline event
 
ENGAGE_API const char *_Nonnull engageGetDeviceId ()
 [SYNC] Returns the device identifier
 
ENGAGE_API int engageEnableWatchdog (int enable)
 [SYNC] Enables or disables the Engine watchdog.
 
ENGAGE_API int engagePlatformNotifyChanges (const char *_Nonnull jsonChangesArray)
 [SYNC] Notifies Engage of changes reported by the application or platform
 
ENGAGE_API int engageEnableNotifications (int enable)
 [SYNC] Notifies Engage of app's willingness to receive notifications
 
ENGAGE_API int engageRefreshAudioDevices (void)
 [ASYNC] Requests that the Engine update its audio device registry
 
ENGAGE_API int engageReconfigureGroup (const char *_Nonnull id, const char *_Nonnull jsonConfiguration)
 [ASYNC] Requests that the Engine reconfigure a group
 
ENGAGE_API int engageBeginFileRecording (const char *_Nonnull jsonParams)
 [ASYNC] Requests that the Engine begin recording audio to a file
 
ENGAGE_API int engageEndFileRecording (const char *_Nonnull id)
 [ASYNC] Requests that the Engine end recording audio to a file
 
ENGAGE_API const char *_Nonnull engageGetActiveFeatureset ()
 [SYNC] Returns JSON object containing the currently active featureset
 
ENGAGE_API int engageSetFipsCrypto (const char *_Nonnull jsonParams)
 [SYNC] Enable FIPS crypto
 
ENGAGE_API int engageIsCryptoFipsValidated (void)
 [SYNC] Returns 1 if crypto is FIPS140-2 validated, otherwise 0
 
ENGAGE_API int engageSetCertStore (const uint8_t *_Nonnull buffer, size_t size, const char *_Nullable passwordHexByteString)
 [SYNC] Set the certstore content via buffer
 
ENGAGE_API int engageVerifyRiff (const char *_Nonnull fn)
 [SYNC] Verifies a recorded RIFF file.
 
ENGAGE_API const char *_Nonnull engageGetRiffDescriptor (const char *_Nonnull fn)
 [SYNC] Returns a descriptor for a RIFF file
 
ENGAGE_API const char *_Nonnull engageGenerateSignature (const uint8_t *_Nonnull block, size_t size, const char *_Nonnull securityCertificateJson)
 [SYNC] Generates a signature for a block using a certificate & its private key
 
ENGAGE_API int engageVerifySignature (const uint8_t *_Nonnull block, size_t size, const char *_Nonnull secureSignatureJson)
 [SYNC] Verifies a signature for a block using a certificate
 

Detailed Description

API functions, codes, and more.

Definition in file EngageInterface.h.

Macro Definition Documentation

◆ _Nonnull

#define _Nonnull

Definition at line 51 of file EngageInterface.h.

◆ _Nullable

#define _Nullable

Definition at line 50 of file EngageInterface.h.

◆ ENGAGE_API

#define ENGAGE_API   __attribute__ ((visibility ("default")))

Definition at line 44 of file EngageInterface.h.

Typedef Documentation

◆ PFN_ENGAGE_HIGH_RES_TIMER_TICK

typedef void(* PFN_ENGAGE_HIGH_RES_TIMER_TICK) (uint32_t tickType, uint64_t ticksSoFar)

Prototype for the high-resolution timer callback.

Definition at line 58 of file EngageInterface.h.

◆ PFN_ENGAGE_LOG_HOOK

typedef void(* PFN_ENGAGE_LOG_HOOK) (int level, const char *_Nonnull tag, const char *_Nonnull message)

Prototype for logging callbacks.

Definition at line 55 of file EngageInterface.h.

Function Documentation

◆ engageAddGroupTimelineEvent()

ENGAGE_API int engageAddGroupTimelineEvent ( const char *_Nonnull id,
const char *_Nonnull jsonParams,
const uint8_t *_Nullable blobData,
size_t blobSize )

[ASYNC] Requests that the Engine add a timeline event

Parameters
idThe ID of the group
jsonParamsParameters for the add operation.
blobDataOptional pointer to an array of bytes for the event.
blobSizeSize of the array of bytes.
Returns
ENGAGE_RESULT_OK if the submission request was successful
See also
PFN_ENGAGE_GROUP_TIMELINE_REPORT

◆ engageBeginFileRecording()

ENGAGE_API int engageBeginFileRecording ( const char *_Nonnull jsonParams)

[ASYNC] Requests that the Engine begin recording audio to a file

Parameters
jsonParamsA JSON object of type ConfigurationObjects::FileRecordingRequest
Returns
ENGAGE_RESULT_OK if the submission request was successful

◆ engageBeginGroupTx()

ENGAGE_API int engageBeginGroupTx ( const char *_Nonnull id,
int txPriority,
uint32_t txFlags )

[ASYNC] Begin audio transmission on a group

Begin audio transmission on a group that is configured for audio (as opposed to data or raw group types).

The application may also set a priority level between 0 and 255 for the transmission burst. This is typically used when a high-priority user needs to override other people transmitting on the group who have lower priorities. Upon receiving prioritized audio packets, other Engage Engines will determine whether their user, if they are already transmitting, should have their transmission usurped or allowed to continue.

Applications should be judicious in how they utilize the transmit priority field as unplanned operation can lead to a confusing and complex user experience in large systems. As a guideline, applications should generally use 0 as the transmit priority for all users and, if the need arises to create priority levels, that those levels be assigned to users according to their role and position in the organization and/or the task at hand.

In addition to transmit priority, the application may also embed bit flags indicating the nature of the transmission. At this time ENGAGE_TXFLAG_EMERGENCY and ENGAGE_TXFLAG_AUTOMATED_SYSTEM are defined.

ENGAGE_TXFLAG_EMERGENCY indicates that the user/entity is transmitting in emergency mode - i.e. the user is in distress or encountering some other kind of emergency. Be aware that this flag is not associated with the transmit priority value. Rather, it is meant to be used as an indicator on receiving user interfaces that the transmitting entity is an emergency state of some sort.

The ENGAGE_TXFLAG_AUTOMATED_SYSTEM flag indicates that the transmitting entity is not a human but rather a mechanical or electronic - such as an AI or other automated system.

Note that transmit priority and transmit flags are only included in the transmitted stream if the group allows for RTP header extensions. For audio groups that have RTP header extensions enabled, the header extension includes the priority and the flags, along with the 16-character alias defined in the Identity JSON object passed in the group creation JSON or, if that was empty, the Identity object passed to engageInitialize().

  • ENGAGE_GROUP_TX_STARTED is fired when transmission begins
  • ENGAGE_GROUP_TX_FAILED is fired if the attempt to transmit fails
  • ENGAGE_GROUP_TX_USURPED_BY_PRIORITY is fired if a higher-priority transmission is received
  • ENGAGE_GROUP_MAX_TX_TIME_EXCEEDED is fired if/when the maximum transmit time for the group is exceeded
  • ENGAGE_GROUP_TX_ENDED when transmission ends
Parameters
idThe ID of the group to transmit to
txPriorityA transmit priority of 0-225 for this transmission
txFlags0 | ENGAGE_TXFLAG_EMERGENCY | ENGAGE_TXFLAG_AUTOMATED_SYSTEM
Returns
ENGAGE_RESULT_OK if the submission request was successful
See also
Application-configurable TX flags, engageInitialize(), engageBeginGroupTxAdvanced(), engageEndGroupTx(), ConfigurationObjects::Group

◆ engageBeginGroupTxAdvanced()

ENGAGE_API int engageBeginGroupTxAdvanced ( const char *_Nonnull id,
const char *_Nonnull jsonParams )

[ASYNC] Begin audio transmission on a group with additional parameters

An extension of engageBeginGroupTx() with parameters incorporated in a JSON object of type AdvancedTxParams. As with engageBeginGroupTx(), these parameters only have meaning if the audio group is configured for RTP header extensions.

Note that transmission of audio generates a great deal of network traffic and therefore this API call, if AdvancedTxParams.includeNodeId is specified, will include an additional 16 bytes of data for every packet that carries the header. If the AdvancedTxParams.alias is also included that will add yet another 16 bytes of data to the RTP packet - driving up bandwidth usage significantly.

Please refer to the "Engage Best Practices" document for more information on how to make the most efficient use of network resources.

Parameters
idThe ID of the group to transmit to
jsonParamsJSON parameters of type ConfigurationObjects::AdvancedTxParams
Returns
ENGAGE_RESULT_OK if the submission request was successful
See also
Application-configurable TX flags, engageInitialize(), engageBeginGroupTx(), engageEndGroupTx(), ConfigurationObjects::Group, ConfigurationObjects::AdvancedTxParams

◆ engageCloseCertStore()

ENGAGE_API int engageCloseCertStore ( void )

[SYNC] Closes the current certificate store (if any)

No events are generated by this API call.

Returns
ENGAGE_RESULT_OK

◆ engageCreateBridge()

ENGAGE_API int engageCreateBridge ( const char *_Nonnull jsonConfiguration)

[ASYNC] Creates a bridge object

Requests creation of a bridge object

  • ENGAGE_BRIDGE_CREATED is fired when the bridge is created.
  • ENGAGE_BRIDGE_CREATE_FAILED is fired if the request fails due to invalid configuration or due to the fact that the bridge object already exists.
Parameters
jsonConfigurationA JSON object of type ConfigurationObjects::Bridge
Returns
ENGAGE_RESULT_OK if the submission request was successful
See also
engageDeleteBridge(), ConfigurationObjects::Bridge

◆ engageCreateCertStore()

ENGAGE_API int engageCreateCertStore ( const char *_Nonnull fileName,
const char *_Nullable passwordHexByteString )

[SYNC] Creates a certificate store

This function creates a certificate store and makes it the active certificate store used for the Engine.

No events are generated by this API call.

Parameters
fileNameThe full path to the file
passwordHexByteStringPassword as a hex byte string (if the file is to be password protected with an additional application password)
Returns
ENGAGE_RESULT_OK if the store was opened

◆ engageCreateGroup()

ENGAGE_API int engageCreateGroup ( const char *_Nonnull jsonConfiguration)

[ASYNC] Creates a group object

Requests creation of a group object according to elements in the JSON configuration parameter. This function is different from other group-related APIs in that it does not have a group ID as a parameter. Rather, the group ID along with other configuration elements for the group are contained in the JSON configuration. In contrast, other group-related APIs need only use the group ID as the identifier and, by then, the object has already been created and is keyed by the ID.

  • ENGAGE_GROUP_CREATED is fired when the group is created.
  • ENGAGE_GROUP_CREATE_FAILED is fired if the request fails due to invalid configuration or due to the fact that the group object already exists.
Parameters
jsonConfigurationA JSON object of type ConfigurationObjects::Group
Returns
ENGAGE_RESULT_OK if the submission request was successful
See also
engageDeleteGroup(), ConfigurationObjects::Group

◆ engageDecrypt()

ENGAGE_API int engageDecrypt ( const uint8_t *_Nonnull src,
size_t size,
uint8_t *_Nonnull dst,
const char *_Nonnull passwordHexByteString )

[SYNC] Decrypt data using the Engine's cryptography module

The inverse of engageEncrypt(). Consult the discussion for engageEncrypt() for more information.

No events are generated by this API call.

Parameters
srcPointer to the source byte array to be decrypted
sizeNumber of bytes in the source byte array
dstPointer to the destination where decrypted data is to be output
passwordHexByteStringHexadecimal representation of the password to be used for key generation
Returns
Number of bytes output to the destination (<= 0 if an error occurred)
See also
engageEncrypt()

◆ engageDeleteBridge()

ENGAGE_API int engageDeleteBridge ( const char *_Nonnull id)

[ASYNC] Deletes a bridge object

Requests deletiom of a bridge object

  • ENGAGE_BRIDGE_DELETED is fired when the bridge is deleted.
Parameters
idThe ID of the bridge
Returns
ENGAGE_RESULT_OK if the submission request was successful
See also
engageCreateBridge(), ConfigurationObjects::Bridge

◆ engageDeleteCertStoreCertificate()

ENGAGE_API int engageDeleteCertStoreCertificate ( const char *_Nonnull id)

[SYNC] Deletes a certificate and its private key (if any)

This function deletes a certificate from the store.

No events are generated by this API call.

Parameters
idThe identifier to delete
Returns
ENGAGE_RESULT_OK if operation was successful.

◆ engageDeleteGroup()

ENGAGE_API int engageDeleteGroup ( const char *_Nonnull id)

[ASYNC] Deletes a previously-created group object

The Engine will delete the group, leaving it if necessary, and releasing any resources allocated for the object. If the group to be deleted does not exist, the Engine will simply continue and not report an error.

  • ENGAGE_GROUP_DELETED is fired when the group is deleted.
Parameters
idThe ID of the group to be deleted
Returns
ENGAGE_RESULT_OK if the submission request was successful
See also
engageCreateGroup()

◆ engageDeleteGroupTimelineEvent()

ENGAGE_API int engageDeleteGroupTimelineEvent ( const char *_Nonnull id,
const char *_Nonnull jsonParams )

[ASYNC] Requests that the Engine delete timeline event

Parameters
idThe ID of the group
jsonParamsParameters for the delete operation.
Returns
ENGAGE_RESULT_OK if the submission request was successful
See also
PFN_ENGAGE_GROUP_TIMELINE_REPORT

◆ engageEnableNotifications()

ENGAGE_API int engageEnableNotifications ( int enable)

[SYNC] Notifies Engage of app's willingness to receive notifications

No events are generated by this API call.

  • Parameters
    enableENGAGE_NOTIFICATIONS_ENABLE or ENGAGE_NOTIFICATIONS_DISABLE
    Returns
    ENGAGE_RESULT_OK if successful

◆ engageEnableSyslog()

ENGAGE_API int engageEnableSyslog ( int enable)

[SYNC] Enables or disables logging to syslog.

This output to syslog has no effect on platforms which do not support syslog such as Windows.

No events are generated by this API call.

See also
Syslog Enable/Disable, engageSetLogLevel()
Parameters
enableENGAGE_SYSLOG_ENABLE or ENGAGE_SYSLOG_DISABLE
Returns
ENGAGE_RESULT_OK if successful

◆ engageEnableWatchdog()

ENGAGE_API int engageEnableWatchdog ( int enable)

[SYNC] Enables or disables the Engine watchdog.

This output to syslog has no effect on platforms which do not support syslog such as Windows.

No events are generated by this API call.

See also
Syslog Enable/Disable, engageSetLogLevel()
Parameters
enableENGAGE_WATCHDOG_ENABLE or ENGAGE_WATCHDOG_DISABLE
Returns
ENGAGE_RESULT_OK if successful

◆ engageEncrypt()

ENGAGE_API int engageEncrypt ( const uint8_t *_Nonnull src,
size_t size,
uint8_t *_Nonnull dst,
const char *_Nonnull passwordHexByteString )

[SYNC] Encrypt data using the Engine's cryptography module

Applications can use this function call to encrypt data using the Engine's currently- active symmetric encryption cipher. Typically this cipher is AES256 operating in CBC mode but may be different if a market- or customer-specific cryptographic module is in use.

It is important that the calling application allocate sufficient space in the destination to accommodate the encrypted output.

In the case of AES256-CBC, the minimum output size is in block sizes of 16 bytes for the actual encrypted data PLUS and additional 16 bytes for the CBC Initialization Vector.

For example: assuming a source array size of 12 bytes to be encrypted, the Engine will output 32 bytes to the destination. The first 16 bytes is the Initialization Vector (always 16 bytes for AES), the remaining 16 bytes is the original 12 bytes rounded up to a block size of 16.

For other source sizes, the output size will vary accordingly, for instance:

An input of 3 bytes results in 32 bytes (3 rounded to 16 + 16 for IV) An input of 15 bytes results in 32 bytes (15 rounded to 16 + 16 for IV) An input of 16 results in 48 bytes (16 rounded to 32 + 16 for IV) An input of 104 results in 128 bytes (104 rounded to 112 + 16 for IV)

The password parameter is the hexadecimal representation of the binary data used as basis key material in generating the symmetric key used for encryption. It is important to understand that this is NOT the actual encryption key, rather, it is used as input to a key derivation function in the Engine's cryptography module that generates a symmetric key using a combination of the provided password and an internal salt value. The password is a required value and, while it may be as short as 1 byte; it is recommended that the application utilize passwords that are much longer.

For more information concerning security and encryption, consult the "Security" section of the Engage Developer's Guide.

No events are generated by this API call.

Parameters
srcPointer to the source byte array to be encrypted
sizeNumber of bytes in the source byte array
dstPointer to the destination where encrypted data is to be output
passwordHexByteStringHexadecimal representation of the password to be used for key generation
Returns
Number of bytes output to the destination (<= 0 if an error occurred)
See also
engageDecrypt()

◆ engageEndFileRecording()

ENGAGE_API int engageEndFileRecording ( const char *_Nonnull id)

[ASYNC] Requests that the Engine end recording audio to a file

Parameters
idThe identifier of the recording provided in the call to engageBeginFileRecording
Returns
ENGAGE_RESULT_OK if the submission request was successful

◆ engageEndGroupTx()

ENGAGE_API int engageEndGroupTx ( const char *_Nonnull id)

[ASYNC] Ends transmission on an audio group

  • ENGAGE_GROUP_TX_ENDED when transmission ends
Parameters
idThe ID of the group on which to end transmission
Returns
ENGAGE_RESULT_OK if the submission request was successful
See also
Application-configurable TX flags, engageInitialize(), engageBeginGroupTx(), engageEndGroupTx()

◆ engageGenerateMission()

ENGAGE_API const char *_Nonnull engageGenerateMission ( const char *_Nonnull keyPhrase,
int audioGroupCount,
const char *_Nullable rallypointHost,
const char *_Nullable missionName )

[SYNC] Generates a mission based on a key phrase

Call this function to obtain a JSON descriptor for a mission generated using the supplied key phrase. The mission will contain 1 presence/mission control group and audioGroupCount audio groups.

No events are generated by this API call.

Parameters
keyPhraseA string used as a baseline hash for generating algorithm
audioGroupCountThe number of audio groups to include the mission
rallypointHostThe host address or FQDN of the Rallypoint to use (if any)
missionNameThe mission name to use (if any)
Returns
Zero-terminated string representing a JSON object describing a mission

◆ engageGenerateMissionUsingCertStore()

ENGAGE_API const char *_Nonnull engageGenerateMissionUsingCertStore ( const char *_Nonnull keyPhrase,
int audioGroupCount,
const char *_Nullable rallypointHost,
const char *_Nullable missionName,
const char *_Nonnull certStoreFn,
const char *_Nullable certStorePasswordHexByteString,
const char *_Nullable certStoreElement )

[SYNC] Generates a mission based on a key phrase and using a specified certificate store

Call this function to obtain a JSON descriptor for a mission generated using the supplied key phrase. The mission will contain 1 presence/mission control group and audioGroupCount audio groups.

No events are generated by this API call.

Parameters
keyPhraseA string used as a baseline hash for generating algorithm
audioGroupCountThe number of audio groups to include the mission
rallypointHostThe host address or FQDN of the Rallypoint to use (if any)
missionNameThe mission name to use (if any)
certStoreFnThe full path to the certificate store file
certStorePasswordHexByteStringCertificate store password as a hex byte string (if the file is password protected with an additional application password)
certStoreElementThe name of the certificate store element to use. If not specified, the element tagged as "-enginedefault" will be used if available.
Returns
Zero-terminated string representing a JSON object describing a mission

◆ engageGenerateSignature()

ENGAGE_API const char *_Nonnull engageGenerateSignature ( const uint8_t *_Nonnull block,
size_t size,
const char *_Nonnull securityCertificateJson )

[SYNC] Generates a signature for a block using a certificate & its private key

No events are generated by this API call.

Returns
SecureSignature JSON as a string

◆ engageGetActiveFeatureset()

ENGAGE_API const char *_Nonnull engageGetActiveFeatureset ( )

[SYNC] Returns JSON object containing the currently active featureset

No events are generated by this API call.

Returns
Zero-terminated JSON string of Configuration::Featureset object

◆ engageGetActiveLicenseDescriptor()

ENGAGE_API const char *_Nonnull engageGetActiveLicenseDescriptor ( )

[SYNC] Returns the currently-active license descriptor

Call this function to obtain a JSON descriptor of the license currently in use by the Engine. If the Engine is operating in unlicensed mode, a descriptor is still returned albeit with most elements empty.

No events are generated by this API call.

Returns
Zero-terminated string representing a JSON object of type ConfigurationObjects::LicenseDescriptor

Example:

{
"activationCode": "",
"cargo": "",
"deviceId": "",
"entitlement": "",
"expires": 0,
"expiresFormatted": "",
"flags": 0,
"key": "",
"refreshIntervalDays": 0,
"refreshUri": "",
"status": -8,
"type": 0
}
See also
ConfigurationObjects::LicenseDescriptor, engageUpdateLicense(), engageUpdateLicense()

◆ engageGetArrayOfCertificateDescriptorsFromPem()

ENGAGE_API const char *_Nonnull engageGetArrayOfCertificateDescriptorsFromPem ( const char *_Nonnull pem)

[SYNC] Returns a JSON array, with each element being an object describing the certificate PEM.

No events are generated by this API call.

Parameters
pemThe PEM for which the descriptor is desired.
Returns
JSON

◆ engageGetAudioDevices()

ENGAGE_API const char *_Nonnull engageGetAudioDevices ( )

[SYNC] Returns an array of audio device descriptor interface devices in JSON format

No events are generated by this API call.

Returns
Zero-terminated JSON string of array of Configuration::AudioDeviceDescriptor objects

◆ engageGetCertificateDescriptorFromPem()

ENGAGE_API const char *_Nonnull engageGetCertificateDescriptorFromPem ( const char *_Nonnull pem)

[SYNC] Returns a JSON object describing the certificate PEM.

No events are generated by this API call.

Parameters
pemThe PEM for which the descriptor is desired.
Returns
JSON

◆ engageGetCertStoreCertificatePem()

ENGAGE_API const char *_Nonnull engageGetCertStoreCertificatePem ( const char *_Nonnull id)

[SYNC] Returns a certificate in PEM format. The private key (if any) is NOT returned.

No events are generated by this API call.

Returns
Certificate PEM

◆ engageGetCertStoreDescriptor()

ENGAGE_API const char *_Nonnull engageGetCertStoreDescriptor ( void )

[SYNC] Returns a JSON descriptor of the currently opened certificate store.

No events are generated by this API call.

Returns
JSON
See also
ConfigurationObjects::CertStoreDescriptor

◆ engageGetDeviceId()

ENGAGE_API const char *_Nonnull engageGetDeviceId ( )

[SYNC] Returns the device identifier

No events are generated by this API call.

Returns
Zero-terminated string

◆ engageGetHardwareReport()

ENGAGE_API const char *_Nonnull engageGetHardwareReport ( )

[SYNC] Returns a hardware report

No events are generated by this API call.

Returns
Zero-terminated JSON string

◆ engageGetLicenseDescriptor()

ENGAGE_API const char *_Nonnull engageGetLicenseDescriptor ( const char *_Nonnull entitlement,
const char *_Nonnull key,
const char *_Nullable activationCode,
const char *_Nullable manufacturerId )

[SYNC] Returns a license descriptor for the parameters passed in

Call this function to obtain a JSON descriptor of the license that would be used based on the supplied parameters.

Typically applications use this function to determine whether license information is valid in order to provide feedback to a user.

No events are generated by this API call.

Parameters
entitlementThe application's entitlement key
keyThe license key
activationCodeThe activation code for the license on the current device (if any)
manufacturerIdOEM-specific manufacturer ID or null foir default
Returns
Zero-terminated string representing a JSON object of type ConfigurationObjects::LicenseDescriptor

Example:

{
"activationCode": "",
"cargo": "",
"deviceId": "",
"entitlement": "",
"expires": 0,
"expiresFormatted": "",
"flags": 0,
"key": "",
"refreshIntervalDays": 0,
"refreshUri": "",
"status": -8,
"type": 0
}
See also
ConfigurationObjects::LicenseDescriptor, engageGetActiveLicenseDescriptor(), engageUpdateLicense()

◆ engageGetNetworkInterfaceDevices()

ENGAGE_API const char *_Nonnull engageGetNetworkInterfaceDevices ( )

[SYNC] Returns an array of network interface devices in JSON format

No events are generated by this API call.

Returns
Zero-terminated JSON string of array of Configuration::NetworkInterfaceDevice objects

◆ engageGetRiffDescriptor()

ENGAGE_API const char *_Nonnull engageGetRiffDescriptor ( const char *_Nonnull fn)

[SYNC] Returns a descriptor for a RIFF file

Call this function to obtain a JSON descriptor of the RIFF file.

No events are generated by this API call.

Parameters
fnThe path to the file.
Returns
Zero-terminated string representing a JSON object describing the RIFF file

Example:

◆ engageGetVersion()

ENGAGE_API const char *_Nonnull engageGetVersion ( )

[SYNC] Returns the version of the Engine

The version of the Engine is in the format <major>.<minor>.<build>. For example: 1.17.8907.

Major version changes represent substantial changes in the Engine such as entirely new capabilities and generally change very seldom. Minor version changes represent incremental updates such as bug fixes, performance enhancements, and API changes that do not require substantial changes in consuming applications. The minor version resets to 0 whenever a major version change is made.

The build number is an internal tracking number and increments each time the Engine is fully rebuilt for release purposes.

No events are generated by this API call.

Returns
Zero-terminated string in the format <major>.<minor>.<build>

◆ engageImportCertStoreElementFromCertStore()

ENGAGE_API int engageImportCertStoreElementFromCertStore ( const char *_Nonnull id,
const char *_Nonnull srcId,
const char *_Nonnull srcFileName,
const char *_Nonnull srcPasswordHexByteString,
const char *_Nullable tags )

[SYNC] Adds/updates an element (certificate and optionally private key) from another certificate store.

This function adds or updates an element using elements(s) from another certificate store.

No events are generated by this API call.

Parameters
idThe identifier by which the certificate and private key will be referenced
srcIdThe identifier in the source certificate store
srcFileNameThe full path to the source certificate store file
srcPasswordHexByteStringPassword as a hex byte string (if the source file is password protected with an additional application password)
tagsA comma-seperated list of tags
Returns
ENGAGE_RESULT_OK if operation was successful.

◆ engageInitialize()

ENGAGE_API int engageInitialize ( const char *_Nullable enginePolicyConfiguration,
const char *_Nullable userIdentity,
const char *_Nullable tempStoragePath )

[SYNC] Initializes the Engine.

Call this function to initialize the Engine prior starting main operation.

Note that calling this function does not start the Engine. Rather, it prepares the Engine for operation. The application needs to call engageStart() to begin Engine processing operations.

No events are generated by this API call.

Parameters
enginePolicyConfigurationAn optional JSON object of type ConfigurationObjects::EnginePolicy
userIdentityAn optional JSON object of type ConfigurationObjects::Identity
tempStoragePathAn optional read/write path for temporary storage
Returns
ENGAGE_RESULT_OK if successful
See also
engageStart(), ConfigurationObjects::EnginePolicy, ConfigurationObjects::Identity

◆ engageIsCryptoFipsValidated()

ENGAGE_API int engageIsCryptoFipsValidated ( void )

[SYNC] Returns 1 if crypto is FIPS140-2 validated, otherwise 0

No events are generated by this API call.

Returns
1 if crypo is FIPS validated, otherwise 0

◆ engageJoinGroup()

ENGAGE_API int engageJoinGroup ( const char *_Nonnull id)

[ASYNC] Joins a group

The Engine will join the group, including connection to a multicast network or a unicast Rallypoint link as dictated by the group's configuration.

Note that joining a group does not mean that it is ready to receive and/or transmit data and/or audio. Rather, this API is a request to the Engine to begin (and continue) processing for the group - including retries needed for connectivity to a local multicast network or Rallypoint link.

Only once a joined group is actually connected to the network infrastructure will the ENGAGE_GROUP_CONNECTED event fire. Applications should therefore update their UIs according to connection-related events rather than join-related events; unless, of course, join failures are encountered.

  • ENGAGE_GROUP_JOINED is fired when the group has been joined.
  • ENGAGE_GROUP_JOIN_FAILED is fired if the Engine fails to begin join processing for the group
Parameters
idThe ID of the group to be joined
Returns
ENGAGE_RESULT_OK if the submission request was successful
See also
engageLeaveGroup()

◆ engageLeaveGroup()

ENGAGE_API int engageLeaveGroup ( const char *_Nonnull id)

[ASYNC] Leaves a group

This API call will result in the Engine leaving a group, freeing up runtime resources needed for the group's operation. The group object remains, however, and can be joined again at the application's discretion.

  • ENGAGE_GROUP_DISCONNECTED is fired whether the group had successfully connected or not
  • ENGAGE_GROUP_LEFT is fired
Parameters
idThe ID of the group to be left
Returns
ENGAGE_RESULT_OK if the submission request was successful
See also
engageJoinGroup()

◆ engageLogMsg()

ENGAGE_API int engageLogMsg ( int level,
const char *_Nonnull tag,
const char *_Nonnull msg )

[SYNC] Log a message via the Engine's logger

Parameters
levelLogging level
tagTag
msgMessage to be logged
Returns
ENGAGE_RESULT_OK if the request was successful
See also
Logging levels

◆ engageMuteGroupRx()

ENGAGE_API int engageMuteGroupRx ( const char *_Nonnull id)

[ASYNC] Mutes play-out of received audio

Following successful execution of the request, the audio for the group will not be played to the audio output device. However, received audio will continue to buffer inside the active transaction if local buffering has been enabled for the group.

  • ENGAGE_GROUP_RX_MUTED
Parameters
idThe ID of the group to be muted
Returns
ENGAGE_RESULT_OK if the submission request was successful
See also
engageUnmuteGroupRx()

◆ engageMuteGroupTx()

ENGAGE_API int engageMuteGroupTx ( const char *_Nonnull id)

[ASYNC] Mutes microphone audio capture

Following successful execution of the request, audio captured from the microphone will not be tramsitted to the network or written to the timeline (if any).

  • ENGAGE_GROUP_TX_MUTED
Parameters
idThe ID of the group TX to be muted
Returns
ENGAGE_RESULT_OK if the submission request was successful
See also
engageUnmuteGroupTx()

◆ engageOpenCertStore()

ENGAGE_API int engageOpenCertStore ( const char *_Nonnull fileName,
const char *_Nullable passwordHexByteString )

[SYNC] Opens a certificate store

This function opensa certificate store and makes it the active certificate store used for the Engine. The function fails if the file already exists and it cannot be opened due to file corruption, password mismatch, or invalid content.

No events are generated by this API call.

Parameters
fileNameThe full path to the file
passwordHexByteStringPassword as a hex byte string (if the file is password protected with an additional application password)
Returns
ENGAGE_RESULT_OK if the store was opened

◆ engagePlatformNotifyChanges()

ENGAGE_API int engagePlatformNotifyChanges ( const char *_Nonnull jsonChangesArray)

[SYNC] Notifies Engage of changes reported by the application or platform

No events are generated by this API call.

  • Parameters
    jsonChangesArrayAn array of pre-defined strings detailing changes
    Returns
    ENGAGE_RESULT_OK if successful

◆ engagePlatformServiceDiscovered()

ENGAGE_API int engagePlatformServiceDiscovered ( const char *_Nonnull id,
const char *_Nonnull jsonParams )

[ASYNC] Informs the Engine that the application has discovered a service

Call this API to indicate to the Engine that the application has discovered a service on the network that may be usable by the Engine. There is no guarantee that the Engine will use the new service. However, if it does, the Engine will fire ENGAGE_GROUP_ASSET_DISCOVERED

No events are fired as a direct result of this API call. However, indirect events such as ENGAGE_GROUP_ASSET_DISCOVERED and ENGAGE_GROUP_ASSET_REDISCOVERED may be fired if the Engine decides to utilize the service and converts the capabilities offered by the service into usable assets.

Parameters
idThe ID assigned to the service by the application
jsonParamsDetails of the discovered service in a JSON object of type PlatformDiscoveredService
Returns
ENGAGE_RESULT_OK if the submission request was successful
See also
engagePlatformServiceRediscovered(), engagePlatformServiceUndiscovered(), ENGAGE_GROUP_ASSET_DISCOVERED

◆ engagePlatformServiceRediscovered()

ENGAGE_API int engagePlatformServiceRediscovered ( const char *_Nonnull id,
const char *_Nonnull jsonParams )

[ASYNC] Informs the Engine that the application has rediscovered a service

This API call is much like engagePlatformServiceDiscovered() but typically called when the application has rediscovered the service - under conditions such as certain service parameters having changed like address or port number.

No events are fired as a direct result of this API call. However, indirect events such as ENGAGE_GROUP_ASSET_DISCOVERED and ENGAGE_GROUP_ASSET_REDISCOVERED may be fired if the Engine decides to utilize the service and converts the capabilities offered by the service into usable assets.

Parameters
idThe ID assigned to the service by the application
jsonParamsDetails of the rediscovered service in a JSON object of type PlatformDiscoveredService
Returns
ENGAGE_RESULT_OK if the submission request was successful
See also
engagePlatformServiceDiscovered(), engagePlatformServiceUndiscovered(), ENGAGE_GROUP_ASSET_DISCOVERED

◆ engagePlatformServiceUndiscovered()

ENGAGE_API int engagePlatformServiceUndiscovered ( const char *_Nonnull id)

[ASYNC] Informs that Engine that a previously-discovered service has disappeared

Call this API to inform the Engine that a service which was previously reported by the calls to engagePlatformServiceDiscovered() and/or engagePlatformServiceRediscovered() has no longer available.

No events are fired as a direct result of this API call. However, ENGAGE_GROUP_ASSET_UNDISCOVERED may be fired if the Engine had decided to previously utilize the service and report available assets.

Parameters
idThe ID assigned to the service by the application
Returns
ENGAGE_RESULT_OK if the submission request was successful
See also
engagePlatformServiceDiscovered(), engagePlatformServiceRediscovered(), ENGAGE_GROUP_ASSET_UNDISCOVERED

◆ engageQueryCertStoreContents()

ENGAGE_API const char *_Nonnull engageQueryCertStoreContents ( const char *_Nonnull fileName,
const char *_Nullable passwordHexByteString )

[SYNC] Returns an extended descriptor of named certificate store

This function opens a certificate store and, if successful, returns a JSON descriptor describing all publicly-available information and contents.

No events are generated by this API call.

Parameters
fileNameThe full path to the file
passwordHexByteStringPassword as a hex byte string (if the file is password protected with an additional application password)
Returns
JSON

◆ engageQueryGroupHealth()

ENGAGE_API int engageQueryGroupHealth ( const char *_Nonnull id)

[ASYNC] Requests that the Engine deliver a health report for the group

Parameters
idThe ID of the group
Returns
ENGAGE_RESULT_OK if the submission request was successful
See also
PFN_ENGAGE_GROUP_HEALTH_REPORT

◆ engageQueryGroupStats()

ENGAGE_API int engageQueryGroupStats ( const char *_Nonnull id)

[ASYNC] Requests that the Engine deliver a statistics report for the group

Parameters
idThe ID of the group
Returns
ENGAGE_RESULT_OK if the submission request was successful
See also
PFN_ENGAGE_GROUP_STATS_REPORT

◆ engageQueryGroupTimeline()

ENGAGE_API int engageQueryGroupTimeline ( const char *_Nonnull id,
const char *_Nonnull jsonParams )

[ASYNC] Requests that the Engine deliver a timeline report for the group

Parameters
idThe ID of the group
jsonParamsParameters for the query operation. TODO: Shaun, where do I find this definition?
Returns
ENGAGE_RESULT_OK if the submission request was successful
See also
PFN_ENGAGE_GROUP_TIMELINE_REPORT

◆ engageReconfigureGroup()

ENGAGE_API int engageReconfigureGroup ( const char *_Nonnull id,
const char *_Nonnull jsonConfiguration )

[ASYNC] Requests that the Engine reconfigure a group

Parameters
idThe ID of the group
jsonConfigurationA JSON object of type ConfigurationObjects::Group
Returns
ENGAGE_RESULT_OK if the submission request was successful

◆ engageRefreshAudioDevices()

ENGAGE_API int engageRefreshAudioDevices ( void )

[ASYNC] Requests that the Engine update its audio device registry

Returns
ENGAGE_RESULT_OK if the submission request was successful
See also
PFN_ENGAGE_ENGINE_AUDIO_DEVICES_REFRESHED

◆ engageRegisterEventCallbacks()

ENGAGE_API int engageRegisterEventCallbacks ( const EngageEvents_t *_Nonnull pEvents)

[SYNC] Registers application event handlers with the Engine

The EngageEvents_t structure contains function pointers to callbacks defined in the application for events generated by the Engine which the applications wishes to handle. Event handlers that are set to null will cause the Engine to generate a warning in the log that the event handler is not found.

No events are generated by this API call.

Parameters
pEventspointer to an EngageEvents_t structure
Returns
ENGAGE_RESULT_OK if successful
See also
eventCallbacks

◆ engageRegisterGroupRtpHandler()

ENGAGE_API int engageRegisterGroupRtpHandler ( const char *_Nonnull id,
uint16_t payloadId )

[ASYNC] Registers the application as the handler for an RTP payload

Instructs the Engine that RTP packets received with the indicated payload ID are to be handled by the application via a callback event rather than processed by the Engine. The payload ID may be any valid RTP payload ID - including RTP payloads that would normally be handled by the Engine. In fact, having the application register as the handler for RTP payloads that would normally be handled by the Engine has the effect of "muting" the Engine's processing of those payloads.

Note that registration of payload IDs are cumulative - meaning that calling this API does not remove registration of a previously-registered payload ID. Rather the newly-registered payload ID is added to a list for the group that the Engine will pass up to the application for processing.

No events are generated by this API call.

Parameters
idThe ID of the group for which to register
payloadIdThe RTP payload ID
Returns
ENGAGE_RESULT_OK if the submission request was successful
See also
engageUnregisterGroupRtpHandler(), engageSendGroupRtp()

◆ engageSendGroupBlob()

ENGAGE_API int engageSendGroupBlob ( const char *_Nonnull id,
const uint8_t *_Nonnull blob,
size_t size,
const char *_Nonnull jsonParams )

[ASYNC] Send an application-structured byte array to a group as an Engine-managed blob

Call this function to have the Engine transmit an application-defined byte array on a group that is configured for RTP or Presence.

While largely the same as engageSendGroupRtp(), this function differs in that the Engine will include a BLOB header with the transmission identifying the node ID of the transmitter - the source - as well as a node ID of the target (or a null node ID if the message is intended for everyone).

Be aware that these node IDs are each 16 bytes in size and therefore result in overhead of at least 32 bytes on a per-messages basis. This use of 32 bytes therefore results in 32 bytes less data that should be included in the data section of the blob in order to fit within the recommended 512-byte limit of restricted UDP MTUs.

Blobs may be sent on Presence or Audio groups but not Raw groups. When sending a blob on an audio group, the Engine requires that the jsonParams parameter contains an RtpHeader JSON object that includes, at minimum, the RTP payload ID to use. This much like the requirement as specified for engageSendGroupRtp(). The Engine follows much the same procedure as when using engageSendGroupRtp(). However, whereas engageSendGroupRtp() requires receiving Engine instances to register for events for the payload ID in question, blob transmission does not. Only the transmitting Engine need set the payload and, as per the discussion for engageSendGroupRtp(), that payload ID must be valid.

Blobs sent on Presence groups do not have a requirement for the RtpHeader JSON object. If it is provided, it will be ignored by the Engine.

Engine instances receiving the transmitted blob will fire the ENGAGE_GROUP_BLOB_RECEIVED event, passing up the blob payload data along with a JSON object describing it. Note that if the blob is being transmitted to a particular node, only that node's application will receive the ENGAGE_GROUP_BLOB_RECEIVED event.

Note: The application must ensure that the size of the data to be transmitted will fit inside a restricted-size UDP MTU which may be encrypted. As a best practice, applications should limit the number of bytes to be sent to 512 bytes.

  • ENGAGE_GROUP_BLOB_SENT when the data is sent
  • ENGAGE_GROUP_BLOB_SEND_FAILED if an error occurs
Parameters
idThe ID of the group
blobPointer to a byte array to send
sizeNumber of bytes to send from the byte array
jsonParamsBlob transmission JSON object of type ConfigurationObjects::BlobInfo
Returns
ENGAGE_RESULT_OK if the submission request was successful
See also
ConfigurationObjects::BlobInfo, ENGAGE_GROUP_BLOB_RECEIVED, engageSendGroupBlob(), engageCreateGroup()

◆ engageSendGroupRaw()

ENGAGE_API int engageSendGroupRaw ( const char *_Nonnull id,
const uint8_t *_Nonnull raw,
size_t size,
const char *_Nonnull jsonParams )

[ASYNC] Send an application-structured byte array to a group with minimal Engine involvement

Call this function to have the Engine transmit raw data to the group. In contrast to engageSendGroupBlob() and engageSendGroupRtp(), the Engine does not perform any processing on the data other than to encrypt it for transmission - assuming the group is encrypted. The application is wholly responsible for meta data associated with the data such as headers. Other Engine instances receiving the data will be notified via the ENGAGE_GROUP_RAW_RECEIVED event.

This function is only valid for groups of type "Raw" - as specified in the call to engageCreateGroup().

The Raw group type along with this API call and the ENGAGE_GROUP_RAW_RECEIVED are particularly useful in environments where an application needs to interact with a legacy or third-party system using data structured in a very particular format. A Raw group may, for example, be used to interact with IoT devices, video streamers, or other entities which the Engage Engine does not natively support.

Alternatively, Raw groups may be used as a means for Engage-based applications to implement secured, proprietary data exchange with each other.

Note: The application must ensure that the size of the data to be transmitted will fit inside a restricted-size UDP MTU which may be encrypted. As a best practice, applications should limit the number of bytes to be sent to 512 bytes.

  • ENGAGE_GROUP_RAW_SENT when the data is sent
  • ENGAGE_GROUP_RAW_SEND_FAILED if an error occurs
Parameters
idThe ID of the group
rawPointer to a byte array to send
sizeNumber of bytes to send from the byte array
jsonParamsOptional parameters in JSON format TODO: Shaun, where is this defined?
Returns
ENGAGE_RESULT_OK if the submission request was successful
See also
ENGAGE_GROUP_RAW_RECEIVED, engageSendGroupBlob(), engageSendGroupRtp(), engageCreateGroup()

◆ engageSendGroupRtp()

ENGAGE_API int engageSendGroupRtp ( const char *_Nonnull id,
const uint8_t *_Nonnull payload,
size_t size,
const char *_Nonnull jsonParams )

[ASYNC] Send an application-structured byte array to a group as a specialized RTP payload

Call this function to have the Engine transmit an application-defined byte array on a group that encapsulates data in RTP packets - i.e. groups of type "Audio".

In order to carry out this operation, the Engine wraps the transmitted data in an RTP packet - i.e. with an RTP header and, on the receiving end, processes that RTP packet. As a result, the application must specify a valid RTP payload type for the RTP header defined in the jsonParams parameters - all other fields in that object are optional. Once the RTP packet is created, it follows the same path through the Engine as other RTP packets - that being through the COMSEC encryption layer if necessary if the group is encrypted and, then, onward to the network. If the network connection is via multicast, the packet is queued and sent to the multicast otherwise, in a unicast environment, the packet is forwarded through the Rallpoint link via TLS to a Rallypoint node/

This function is only valid for groups of type "Audio" - as specified in the call to engageCreateGroup().

In order to receive payloads sent via RTP, receiving Engine instances must be passed the payload ID in the call to engageRegisterGroupRtpHandler(). This will cause the receiving Engine to fire the ENGAGE_GROUP_RTP_RECEIVED event, passing up the payload along with a JSON object of type RtpHeader.

Be aware that Engage-specific RTP header extensions for the group will NOT be sent for custom RTP payloads. Applications that wish to convey identifying information (such as source and target(s)) in the transmission need to include that information in the payload and be responsible for handling those elements.

Note: The application must ensure that the size of the data to be transmitted will fit inside a restricted-size UDP MTU which may be encrypted. As a best practice, applications should limit the number of bytes to be sent to 512 bytes.

  • ENGAGE_GROUP_RTP_SENT when the data is sent
  • ENGAGE_GROUP_RTP_SEND_FAILED if an error occurs
Parameters
idThe ID of the group
payloadPointer to a byte array to send
sizeNumber of bytes to send from the byte array
jsonParamsRTP header parameters in a JSON object of type RtpHeader
Returns
ENGAGE_RESULT_OK if the submission request was successful
See also
jsonRtpHeader, ENGAGE_GROUP_RTP_RECEIVED, engageSendGroupBlob(), engageCreateGroup()

◆ engageSetCertStore()

ENGAGE_API int engageSetCertStore ( const uint8_t *_Nonnull buffer,
size_t size,
const char *_Nullable passwordHexByteString )

[SYNC] Set the certstore content via buffer

An alternative to engageOpenCertStore whereby a buffer is passed to the Engine containing a certificate store's binary data rather having it loaded from file.

No events are generated by this API call.

Parameters
bufferPointer to the certificate store byte array
sizeNumber of bytes in the buffer
passwordHexByteStringHexadecimal representation of the password to be used to decrypt the buffer
Returns
ENGAGE_RESULT_OK on success, other values on failure
See also
engageOpenCertStore()

◆ engageSetCertStoreCertificateP12()

ENGAGE_API int engageSetCertStoreCertificateP12 ( const char *_Nonnull id,
uint8_t *_Nonnull data,
size_t size,
const char *_Nullable password,
const char *_Nullable tags )

[SYNC] Adds/updates a certificate and (optionally) private key using P12 content

This function adds or updates a certificate using P12 as the source container. The container must contain the certificate but does not need to not contain a private key if no private key is to be associated.

No events are generated by this API call.

Parameters
idThe identifier by which the certificate and (optional) private key will be referenced
dataA binary buffer containing the P12 data
sizeSize of the buffer
passwordPassword to the P12 if it is password-protected
tagsA comma-seperated list of tags
Returns
ENGAGE_RESULT_OK if operation was successful.

◆ engageSetCertStoreCertificatePem()

ENGAGE_API int engageSetCertStoreCertificatePem ( const char *_Nonnull id,
const char *_Nonnull certificatePem,
const char *_Nullable privateKeyPem,
const char *_Nullable tags )

[SYNC] Adds/updates a certificate and (optionally) private key using PEM strings

This function adds or updates a certificate using PEM as the source content. PEM for the certificate must be provided but the PEM for the private key may be an emoty string (or null) if no prvate key is to be associated.

No events are generated by this API call.

Parameters
idThe identifier by which the certificate and private key will be referenced
certificatePemCertificate content in PEM format
privateKeyPemPrivate key content in PEM format (optional)
tagsA comma-seperated list of tags
Returns
ENGAGE_RESULT_OK if operation was successful.

◆ engageSetCertStoreCertificateTags()

ENGAGE_API int engageSetCertStoreCertificateTags ( const char *_Nonnull id,
const char *_Nullable tags )

[SYNC] Updates a certificate's tags

This function a certificate's tags. The certificate must already be present in the store.

No events are generated by this API call.

Parameters
idThe identifier by which the certificate and (optional) private key will be referenced
tagsA comma-seperated list of tags
Returns
ENGAGE_RESULT_OK if operation was successful.

◆ engageSetFipsCrypto()

ENGAGE_API int engageSetFipsCrypto ( const char *_Nonnull jsonParams)

[SYNC] Enable FIPS crypto

Parameters
jsonParamsA JSON object of type ConfigurationObjects::FipsCryptoSettings
Returns
ENGAGE_RESULT_OK on success, other values on failure

◆ engageSetGroupRules()

ENGAGE_API int engageSetGroupRules ( const char *_Nonnull id,
const char *_Nonnull jsonParams )

[ASYNC] Sets the audio play-out volume of the group

This API applies rules to the group.

No events are generated by this API call.

Parameters
idThe ID of the group
jsonParamsA JSON object of type ConfigurationObjects::GroupRules
Returns
ENGAGE_RESULT_OK if the submission request was successful

◆ engageSetGroupRxTag()

ENGAGE_API int engageSetGroupRxTag ( const char *_Nonnull id,
uint16_t tag )

[ASYNC] Sets/clear a audio stream subchannel tag

This API instructs the Engine to process RTP streams that have a particular subchannel tag associated with them. A subchannel is a means by which an existing group (including all its network connections and infrastructure) can be used to transmit traffic that, while received by all Engage Engines on the "main" group, is ignored by Engines that are not actively processing the subchannel tag. Subchannels are typically used to create "private" streams within existing streams - generally for purposes of a private communication between a subset of the users on an Engage group. For example, assuming an application has the means by which to coordinate with other instances of itself a numeric identifier (between 1 and 65535) to be used as a "private group", and the tag is set in transmission by calling engageBeginGroupTxAdvanced() with that value; other instances that call engageSetGroupRxTag() with that tag value will "hear" that traffic. Instances that are not aware of the tag will simply ignore the tagged packets.

While this is not a foolproof method by which to create "private" streams between users, it is very efficient and substantially less complicated than coordinating the creation of groups dynamically across an enterprise network that do not run the risk of interfering with hitherto unknown multicast address and port numbers.

To clear the tag on the group, call this function passing 0 as the tag value.

No events are generated by this API call.

Parameters
idThe ID of the group on which to set the subchannel tag
tagThe numeric value of the tag (1-65535), 0 to clear the tag
Returns
ENGAGE_RESULT_OK if the submission request was successful
See also
engageBeginGroupTxAdvanced()

◆ engageSetGroupRxVolume()

ENGAGE_API int engageSetGroupRxVolume ( const char *_Nonnull id,
int left,
int right )

[ASYNC] Sets the audio play-out volume of the group

This API call changes the gain of the left and right audio play-out levels relative to the current hardware-defined play-out level by applying the requested levels as a percentage. Gain levels of 100 percent result in the volume remaining unchanged. Gain levels less that 100 percent cause the volume to be decreased, whereas levels greater than 100 cause the volume to be increased.

The Engine assumes the audio hardware to be capable of stereo output - therefore the reason for separate left and right levels. However, on devices that do not support stereo output, the hardware typically merges the stereo levels to obtain an averaged value for mono output.

On hardware that does support stereo, setting different levels for left and right result in stereo panning - allowing, for example, one group's audio to be played to the left channel with another group's audio played to the right channel.

Note: This call does NOT change the physical hardware audio level as most platforms do not allow for this programmatically as doing so would interfere with audio levels in other applications.

No events are generated by this API call.

Parameters
idThe ID of the group
leftLeft volume level
rightRight volume level
Returns
ENGAGE_RESULT_OK if the submission request was successful

◆ engageSetLoggingOutputOverride()

ENGAGE_API int engageSetLoggingOutputOverride ( const _Nullable PFN_ENGAGE_LOG_HOOK pfnHook)

[SYNC] Sets/clears the output override callback for log messages.

No events are generated by this API call.

Parameters
pfnHookPointer to the callback function. In a Java environment, this needs to be the null-terminated string name of a Java method. A non-null value causes all logging to be done exclusively through the override function - i.e. the Engine will not perform any output of it's own - either to consoles, files, or syslog. A null/empoty value causes the Engine to take over output logging.
Returns
ENGAGE_RESULT_OK if successful

◆ engageSetLogLevel()

ENGAGE_API int engageSetLogLevel ( int level)

[SYNC] Sets the Engine's logging level.

The logging level takes effect immediately and affects output to all targets including the console, system debug log (Windows), and syslog.

No events are generated by this API call.

See also
Logging levels, engageEnableSyslog(), Engage Engine Result Codes
Parameters
levelDesired debugging level
Returns
ENGAGE_RESULT_OK if successful

◆ engageSetLogTagExtension()

ENGAGE_API int engageSetLogTagExtension ( const char *_Nullable tagExtension)

[SYNC] Sets the Engine's log tag extension.

The tag extension takes effect immediately and affects output to all targets including the console, system debug log (Windows), and syslog.

No events are generated by this API call.

See also
engageEnableSyslog(), Engage Engine Result Codes
Parameters
tagExtensionAs string to be added to all tags. A null or zero-length string clears the tag extension.
Returns
ENGAGE_RESULT_OK if successful

◆ engageSetMissionId()

ENGAGE_API int engageSetMissionId ( const char *_Nullable missionId)

[SYNC] Sets the (optional) mission ID for the Engine

Call this function to set an optional mission ID to be used for various operations in the Engine - particularly for Rallypoint registrations.

No events are generated by this API call.

Parameters
missionIdThe mission ID (null or empty string to revert to default)
Returns
ENGAGE_RESULT_OK if the call was successful

◆ engageShutdown()

ENGAGE_API int engageShutdown ( )

[SYNC] Shuts down the Engine

Calling this function will carry out the inverse of engageInitialize(), leaving all groups, destroying all objects and freeing up resources since the last call to engageInitialize(). Typically this function is called as part of the application shutdown procedure or when a full restart of the Engine is required. While this function will close down all resources, be aware that race conditions may arise if the process is in an unstable state during shutdown. Therefore, the application should, instead, perform cleanup of its own by leaving all groups, and destroying all previously-created groups.

Furthermore, as this is a synchronous function call, the application should take care to call it from a thread that will not be impacted by a delay in processing.

No events are generated by this API call.

Returns
ENGAGE_RESULT_OK if successful
See also
engageInitialize()

◆ engageStart()

ENGAGE_API int engageStart ( void )

[ASYNC] Starts the Engine

Once initialized through a call to engageInitialize(), the application must call this function to start the Engine's internal processing logic.

  • PFN_ENGAGE_ENGINE_STARTED is fired when the request completes.

As this is a synchronous function call, the application should take care to call it from a thread that will not be impacted by a delay in processing.

Returns
ENGAGE_RESULT_OK if successful
See also
engageInitialize()

◆ engageStop()

ENGAGE_API int engageStop ( void )

[ASYNC] Stops the Engine's internal processing

This function is the inverse of engageStart(). It will cease all processing in the Engine, including leaving all groups. However, resources that were allocated such as the creation of groups, will not be destroyed by this call.

  • ENGAGE_ENGINE_STOPPED is fired when the request completes.
Returns
ENGAGE_RESULT_OK if successful
See also
engageStart()

◆ engageUnmuteGroupRx()

ENGAGE_API int engageUnmuteGroupRx ( const char *_Nonnull id)

[ASYNC] Unmutes play-out of received audio

Following successful execution of the request, the audio for the group will be played to the audio output device.

  • ENGAGE_GROUP_RX_UNMUTED
Parameters
idThe ID of the group to be unmuted
Returns
ENGAGE_RESULT_OK if the submission request was successful
See also
engageMuteGroupRx()

◆ engageUnmuteGroupTx()

ENGAGE_API int engageUnmuteGroupTx ( const char *_Nonnull id)

[ASYNC] Unmutes microphone audio capture

Following successful execution of the request, the audio captured for the group will be transmitted to the network and written to the timeline (if any)

  • ENGAGE_GROUP_TX_UNMUTED
Parameters
idThe ID of the group TX to be unmuted
Returns
ENGAGE_RESULT_OK if the submission request was successful
See also
engageMuteGroupTx()

◆ engageUnregisterGroupRtpHandler()

ENGAGE_API int engageUnregisterGroupRtpHandler ( const char *_Nonnull id,
uint16_t payloadId )

[ASYNC] Unregisters the application as the handler for an RTP payload

The inverse of engageRegisterGroupRtpHandler(), removing the payload ID as an application-handled payload for the particular group. If the payload ID is one that the Engine would normally process, that functionality will be reinstated.

No events are generated by this API call.

Parameters
idThe ID of the group for which to unregister
payloadIdThe RTP payload ID
Returns
ENGAGE_RESULT_OK if the submission request was successful
See also
engageRegisterGroupRtpHandler()

◆ engageUpdateGroupTimelineEvent()

ENGAGE_API int engageUpdateGroupTimelineEvent ( const char *_Nonnull id,
const char *_Nonnull jsonParams,
const uint8_t *_Nullable blobData,
size_t blobSize )

[ASYNC] Requests that the Engine update a timeline event

Parameters
idThe ID of the group
jsonParamsParameters for the add operation.
blobDataOptional pointer to an array of bytes for the event.
blobSizeSize of the array of bytes.
Returns
ENGAGE_RESULT_OK if the submission request was successful
See also
PFN_ENGAGE_GROUP_TIMELINE_REPORT

◆ engageUpdateLicense()

ENGAGE_API int engageUpdateLicense ( const char *_Nonnull entitlement,
const char *_Nonnull key,
const char *_Nullable activationCode,
const char *_Nullable manufacturerId )

[ASYNC] Update the active license with new parameters

Call this function to install a new license and/or activation code in the Engine. Assuming the parameters are valid, the Engine will put the new license into effect right away - regardless of whether the license is active, expired, or expiring in the near future.

  • ENGAGE_LICENSE_CHANGED
  • ENGAGE_LICENSE_EXPIRED if the license has expired
  • ENGAGE_LICENSE_EXPIRING if the license will expire soon
Parameters
entitlementThe application's entitlement key
keyThe license key
activationCodeThe activation code for the license on the current device (if any)
manufacturerIdOEM-specific manufacturer ID or null foir default
Returns
ENGAGE_RESULT_OK if the submission request was successful

◆ engageUpdatePresenceDescriptor()

ENGAGE_API int engageUpdatePresenceDescriptor ( const char *_Nonnull id,
const char *_Nonnull descriptorJson,
int forceBeacon )

[ASYNC] Updates the application-defined elements of a presence descriptor

Call this function to pass into the Engine that information which the application wishes to be transmitted as part of the Engine's normal presence declarations. The next time the Engine sends its presence descriptor on the group specified, the new data will be included.

As presence declarations are only sent periodically according to a bandwidth-sensitive algorithm, the updated presence descriptor may not be sent right away. To request the Engine to send the updated presence descriptor as soon as possible, set forceBeacon to 1.

No events are generated by this API call.

Parameters
idThe ID of the group
descriptorJsonA required JSON object of type ConfigurationObjects::PresenceDescriptor
forceBeacon1 to force the Engine to send the presence descriptor immediately
Returns
ENGAGE_RESULT_OK if the submission request was successful
See also
jsonPresenceDescriptor

◆ engageVerifyRiff()

ENGAGE_API int engageVerifyRiff ( const char *_Nonnull fn)

[SYNC] Verifies a recorded RIFF file.

This function verifies a signed, recorded RIFF file. It returns ENGAGE_RESULT_OK (0) on success.

No events are generated by this API call.

Parameters
fnThe path to the file.
Returns
ENGAGE_RESULT_OK if operation was successful.

◆ engageVerifySignature()

ENGAGE_API int engageVerifySignature ( const uint8_t *_Nonnull block,
size_t size,
const char *_Nonnull secureSignatureJson )

[SYNC] Verifies a signature for a block using a certificate

No events are generated by this API call.

Returns
JSON