Integrating the Honeygain SDK with Windows C/C++ applications

This guide will go through the process of integrating and using Honeygain SDK in your C/C++ Windows application. It can also be integrated with any technology that supports the C ABI on Windows.

info

Don't forget to generate your Honeygain SDK API Key and download SDK from Developers dashboard first.

Integration

On Windows operating system SDK service is provided for 64-bit and 32-bit architectures. SDK service dynamic-link libraries x64\bin\hgsdk.dll or x86\bin\hgsdk.dll should be loaded by your applications executable. It is recommended to place them in the same directory as your applications executable file depending on its architecture.

With Visual Studio

If using Visual Studio you can take following steps to integrate SDK service:

• Right-click on your project in Solution Explorer and select Properties.
• Go to Configuration Properties > C/C++ > General.
  • Make sure that Configuration is set to All Configurations.
  • When targeting 64-bit architecture make sure that Platform is set to x64 and in Additional Include Directories add path to the SDK service header file x64\include\hgsdk.h.
  • When targeting 32-bit architecture make sure that Platform is set to Win32 and in Additional Include Directories add path to the SDK service header file x86\include\hgsdk.h.
• Go to Configuration Properties > Linker > General.
  • Make sure that Configuration is set to All Configurations.
  • When targeting 64-bit architecture make sure that Platform is set to x64 and in Additional Library Directories add path to the SDK service import library x64\lib\hgsdk.dll.lib.
  • When targeting 32-bit architecture make sure that Platform is set to Win32 and in Additional Library Directories add path to the SDK service import library x86\lib\hgsdk.dll.lib.
• Go to Configuration Properties > Linker > Input.
  • Make sure that Configuration is set to All Configurations and Platform is set to All Platforms.
  • In Additional Dependencies add hgsdk.dll.lib.
• Go to Configuration Properties > Build Events > Post-Build Event.
  • Make sure that Configuration is set to All Configurations.
  • When targeting 64-bit architecture make sure that Platform is set to x64 and in Command Line add

    copy /Y "<path to>\x64\bin\hgsdk.dll" "$(OutDir)"
  • When targeting 32-bit architecture make sure that Platform is set to Win32 and in Command Line add

    copy /Y "<path to>\x86\bin\hgsdk.dll" "$(OutDir)"
  • Replace <path to> with the path to the directory where SDK service dynamic-link library is located.

info

Full working example can be found in samples/windows directory of the downloaded Honeygain SDK.

Function reference

note

hgsdk_start() and hgsdk_stop() are non-blocking. Internally, starting and stopping the Honeygain SDK service are asynchronous operations, so there can be a slight delay before the action takes effect.

---

hgsdk_start

Start the SDK service.

int32_t hgsdk_start(const char *api_key, int32_t *state);

Parameters

Name	Type	Description
api_key	const char*	Your API key provided by Honeygain SDK.
state	int32_t*	Out: consent state. Set to 1 if user consent was previously given, otherwise 0.

Returns

0 on success; otherwise a negative error code.

Remarks

• Checks whether explicit user consent was given before. The current consent state is returned via *state.
• If consent was previously given, the SDK service starts. If not, the service does not start and *state is set to 0.
• If the service is already running, the old instance is stopped and a new one is started with the provided API key.
• api_key is copied by the SDK; its memory does not need to remain valid after the call returns.

note

It is recommended to obtain user consent before starting the SDK service.

---

hgsdk_stop

Stop the SDK service.

int32_t hgsdk_stop(void);

Returns

0 on success; otherwise a negative error code.

Remarks

• Stops the SDK service if it is running and releases all resources.
• If the service is not running, this function does nothing.

note

It is recommended to stop the SDK service before closing your application to ensure all resources are released properly.

---

hgsdk_is_running

Check if the SDK service is running.

int32_t hgsdk_is_running(int32_t *state);

Parameters

Name	Type	Description
state	int32_t*	Out: set to 1 if the service is running, otherwise 0.

Returns

0 on success; otherwise a negative error code.

---

hgsdk_opt_in

Provide user consent.

int32_t hgsdk_opt_in(void);

Returns

0 on success; otherwise a negative error code.

Remarks

• Persists that user consent was given and informs the SDK service that it may start.
• Subsequent calls to hgsdk_start() will be allowed to start the service.

---

hgsdk_opt_out

Revoke user consent.

int32_t hgsdk_opt_out(void);

Returns

0 on success; otherwise a negative error code.

Remarks

• Persists that user consent was revoked and informs the SDK service that it should stop if running.
• Subsequent calls to hgsdk_start() will not be allowed to start the service.

---

hgsdk_is_opted_in

Check whether user consent was given.

int32_t hgsdk_is_opted_in(int32_t *state);

Parameters

Name	Type	Description
state	int32_t*	Out: set to 1 if consent was given, otherwise 0.

Returns

0 on success; otherwise a negative error code.

Remarks

• Returns the stored consent state via *state.

---

hgsdk_request_consent

Display the default user agreement window and capture consent.

int32_t hgsdk_request_consent(int32_t *state);

Parameters

Name	Type	Description
state	int32_t*	Out: set to 1 if the user accepts, otherwise 0.

Returns

0 on success; otherwise a negative error code.

Remarks

• Shows the default user agreement UI.
• If the user accepts, consent is stored and the SDK service may start. Subsequent hgsdk_start() calls are allowed.
• If the user declines or closes the window, subsequent hgsdk_start() calls are not allowed unless consent was previously given.

note

This function is blocking and returns only after the user accepts or declines the agreement.

---

hgsdk_log

Enable logging for the SDK service.

int32_t hgsdk_log(const char *dir);

Parameters

Name	Type	Description
dir	const char*	Directory where log files will be stored. If NULL or empty, logs are created in the current working directory.

Returns

0 on success; otherwise a negative error code.

Remarks

• Enables logging and writes logs to the specified directory (created if it does not exist).
• Logs are also written to standard output.
• Subsequent calls to hgsdk_log() create a new log file in the specified directory.

---

hgsdk_mute

Disable logging for the SDK service.

int32_t hgsdk_mute(void);

Returns

0 on success; otherwise a negative error code.

Remarks

• Disables logging: closes any open log file and stops writing to standard output.
• Existing log files are not deleted and can be inspected for debugging.