C++ API Reference

The C++ API provides direct access to the AppGuard library functions.

Core Functions

void AG_init(const char *app_handle, AppOnQuitCallback on_quit_callback, bool quit_immediate)

Initializes the AppGuard library for application instance management.

The ap handle could be a window name or unique. It is used internally by the library. This function must be called first before any other functions in the library.

Parameters:

  • app_handle – A const char* representing the unique application identifier.

  • on_quit_callback – A callback function to be called when the application quits immediately. This callback will only be invoked on secondary instances if the quit_immediate boolean is set to true. It will not be called once the library cleans up.

  • quit_immediate – A boolean indicating whether to quit immediately when a secondary instance of the app is detected or not. If set to false, the closing of the library/application will be left to the user.

void AG_release()

Releases AppGuard resources and performs cleanup.

Cleans up the current app instance and ipc related resources.

bool AG_is_loaded()

Checks if the AppGuard library is loaded and initialized.

Call this function to check if the library is loaded correctly. Returns false if the library is not initialized or was released.

Returns:

A bool indicating whether the library is loaded.

bool AG_is_primary_instance()

Determines if this is the primary instance of the application.

This function is used internally by the library for surtain checks E.G. if should the app quit if the current process is not a primary instance.

Returns:

A bool indicating whether this is the primary application instance.

IPC Functions

void AG_create_IPCMsg(IPCMsg *msg, const char *msg_handle, IPCMsgCallback callback)

Creates an IPC message structure for inter-process communication.

Call this function to initialize the ipc message with a handle and a callback. The handle is used for message lookup. Through it, the library calls the function you provided, passing an IPCMsgData as an argument. This is used in conjunction with the AG_register_msg and AG_send_msg_request functions.

Parameters:

  • msg – A pointer to an IPCMsg structure to be initialized.

  • msg_handle – A const char* representing the message identifier.

  • callback – A callback function to be invoked using the message handle when an IPC message request is received.

void AG_register_msg(IPCMsg *msg)

Registers an IPC message for receiving communications.

Call this function after creating the IPC message. The function places an id on the message struct which can be used to unregister the message

Parameters:

msg – A pointer to an IPCMsg structure to register.

void AG_unregister_msg(int msg_id)

Unregisters an IPC message by its ID.

Parameters:

msg_id – An integer representing the message ID to unregister.

void AG_send_msg_request(IPCMsgData *msg_request)

Sends an IPC message request to another process instance.

This function can be used to send an IPC message to a live instance of the program. This could typically be used to forward data to the program from other secondary instances before exiting. E.G. Command line arguments. Only registered messages that are foudn by the same handle provided in the IPCMsgData struct will be called with the IPCMsgData argument passed to them.

Parameters:

msg_request – A pointer to an IPCMsgData structure containing the message to send.

Utility Functions

int AG_get_process_id()

Retrieves the current process ID.

Returns:

An integer representing the current process ID.

void AG_focus_window(const wchar_t *window_name)

Focuses a window by its name.

Parameters:

window_name – A const wchar_t* representing the name of the window to focus.

Data Structures

struct IPCMsg

Structure representing a registered IPC message handler.

Public Members

int msg_id

Unique message identifier.

Handle used for invoking message callbacks.

const char *msg_handle

Message handle string.

IPCMsgCallback callback

Callback function for handling messages.

struct IPCMsgData

Structure representing IPC message data.

Public Members

const char *msg_handle

Message handle identifier.

Handle used for invoking message callbacks.

const wchar_t *msg_data

The actual message content.

Message data. String content. 8 KB max.

Type Definitions

typedef void (*IPCMsgCallback)(const IPCMsgData *msg_data)

Callback function type for handling IPC messages.

Param msg_data:

A pointer to the received IPC message data.

typedef void (*AppOnQuitCallback)()

Callback function type for application quit notifications.

Macros

APPGUARD_API