C/C++ API ReferencePermanent link for this heading

The Fabasoft app.telemetry Software-Telemetry C/C++ API allows you to instrument any C/C++ application with instrumentation points to see what's going on in complex applications.

Constants(C/C++)Permanent link for this heading

This chapter lists the available constants to be used for instrumenting your C/C++ application.

Flags (C/C++)Permanent link for this heading

Flags are used to specify the type of an event and are passed as argument to every event call. They are predefined by the API with the data type UInt8 and have the following possible values:

  • APM_FLAG_NONE
  • APM_FLAG_ENTER
  • APM_FLAG_LEAVE
  • APM_FLAG_WAIT
  • APM_FLAG_WARNING
  • APM_FLAG_ERROR
  • APM_FLAG_PROCESS_INFO

For more details about the flags and there meaning see the general chapter “Flags”.

Log Level (C/C++)Permanent link for this heading

An event will only be logged if the event-level is lower or equal to the value selected in the session or log-definition. The log levels are predefined by the API with the data type UInt8 and have the following possible values:

  • APM_EVENT_LEVEL_LOG
  • APM_EVENT_LEVEL_IPC (only internal)
  • APM_EVENT_LEVEL_NORMAL
  • APM_EVENT_LEVEL_DETAIL
  • APM_EVENT_LEVEL_DEBUG

For more details about the log levels and there meaning see the general chapter “Log Level”.

Parameter Types (C/C++)Permanent link for this heading

Parameter types provide type information of parameters in a call to APMEventArgs (see “Method APMEventArgs (C/C++)”)

Name

Value

Description

APM_PARAMETERTYPE_INT32

1

parameter is of type UInt32

APM_PARAMETERTYPE_INT64

2

parameter is of type UInt64

APM_PARAMETERTYPE_STRING

3

parameter is an utf-8 encoded string(0 terminated)

Predefined Modules (C/C++)Permanent link for this heading

For a list of available standard modules with a set of predefined events see chapter “Standard Modules”.

Predefined Events (C/C++)Permanent link for this heading

The SDK already provides a set of predefined events used for general purpose. For a full listing of all available predefined events see the generic chapter “Predefined Events”.

Error/Trace Events:

Use these standard events to mark error, warning or info conditions in your application like in the following example:

  • APM_EVENT_ERROR
  • APM_EVENT_WARNING
  • APM_EVENT_INFO
  • APM_EVENT_TRACE

Code Example

APMEventStr(anymodule, APM_EVENT_ERROR, APM_EVENT_LEVEL_NORMAL, APM_FLAG_ERROR, "My error message”);

APMEventStr(anymodule, APM_EVENT_WARNING, APM_EVENT_LEVEL_NORMAL, APM_FLAG_WARNING, "My warning message”);

APMEventStr(anymodule, APM_EVENT_INFO, APM_EVENT_LEVEL_NORMAL, APM_FLAG_NONE, "My info message”);

APMEventStr(anymodule, APM_EVENT_TRACE, APM_EVENT_LEVEL_DETAIL, APM_FLAG_ERROR, "My trace message”);

Data types (C/C++)Permanent link for this heading

APMApplicationHandle (C/C++)Permanent link for this heading

APMApplicationHandle is used to identify an application registered in your process by calling APMRegisterApplication (see “Method APMRegisterApplication (C/C++)”). The handle is only valid in the same process until you call APMUnregisterApplication (see “Method APMUnregisterApplication (C/C++)).

Type Declaration

typedef UInt32 APMModuleHandle;

APMModuleHandle (C/C++)Permanent link for this heading

APMModuleHandle is used to identify a module registered in your process by calling APMRegisterModule (see “Method APMRegisterModule (C/C++)”). The handle is valid only in the same process until you call APMUnregisterModule (see “Method APMUnregisterModule (C/C++)”).

Type Declaration

typedef UInt32 APMModuleHandle;

APMEventId (C/C++)Permanent link for this heading

APMEventId is used to identify an event. The event id must be unique per module and you are free to choose a value. Avoid using predefined event ids (see “Predefined Events”).
APMEventId is declared as:

Type Declaration

typedef UInt64 APMEventId;

APMEventLevel (C/C++)Permanent link for this heading

APMEventLevel is used to specify the importance of an event.

Type Declaration

typedef UInt8  APMEventLevel;

Possible values are:

  • APM_EVENT_LEVEL_LOG
  • APM_EVENT_LEVEL_IPC
  • APM_EVENT_LEVEL_NORMAL
  • APM_EVENT_LEVEL_DETAIL
  • APM_EVENT_LEVEL_DEBUG

APMEventFlags (C/C++)Permanent link for this heading

APMEventFlags is used to specify the type of an event.

Type Declaration

typedef UInt8  APMEventFlags;

Possible values are:

  • APM_FLAG_NONE
  • APM_FLAG_ENTER
  • APM_FLAG_LEAVE
  • APM_FLAG_WAIT
  • APM_FLAG_WARNING
  • APM_FLAG_ERROR

APMParameterType (C/C++)Permanent link for this heading

APMParameterType is used to specify the type of the parameter (see “Method APMEventArgs (C/C++)”).

Code Definition

typedef UInt8  APMParameterType;

Possible values are:

  • APM_PARAMETERTYPE_INT32
  • APM_PARAMETERTYPE_INT64
  • APM_PARAMETERTYPE_STRING

EnumAppFilterValuesCallback (C/C++)Permanent link for this heading

Applications may register a callback when calling APMRegisterApplication (see Method APMRegisterApplication (C/C++)”). The callback should enumerate all valid filter values by repeatedly calling APMRegisterFilterValue (see “Method APMRegisterFilterValue (C/C++)”) to register all valid values, that may be selected when starting a Software-Telemetry session. The callback will be triggered by the app.telemetry server, if no filter values are defined for the registered application or once per hour to refresh the values.

Code Definition

typedef void (APMFUNC *EnumAppFilterValuesCallback)();

APMContext (C/C++)Permanent link for this heading

Values of type APMContext need to be passed during inter-process communication to provide the caller context to the invoked program (see “Method APMGetContext (C/C++)” and “Method APMAttachContext (C/C++)”).

Code Definition

typedef unsigned char APMContext[16];

APMSyncMark (C/C++)Permanent link for this heading

Values of type APMSyncMark need to be passed during inter-process communication to provide time sequence information (see “Method APMGetSyncMark (C/C++)” and “Method APMSetSyncMark (C/C++)”).

Code Definition

typedef unsigned char APMSyncMark[16];

APMParamHandle (C/C++)Permanent link for this heading

Pointers of type APMParamHandle are used to register multiple parameters for use with APMEventParam (see “Method APMEventParam (C/C++)” and “Parameter Functions (C/C++)”).

Code Definition

typedef void *APMParamHandle;

Registration Functions (C/C++)Permanent link for this heading

Method APMRegisterApplication (C/C++)Permanent link for this heading

Call this function once to provide information about the context of the application.

Syntax

APMDECL_EXTERN APMApplicationHandle APMFUNC APMRegisterApplication(
    const char *app
Name,
    const char *app
Id,
    const char *app
TierName,
    const char *app
TierId,
    EnumAppFilter
ValuesCallback filterCallback);

Parameters:

  • appName: The name of your application (utf-8 encoded)
  • appId: The Id of your application (utf-8 encoded)
  • appTierName: The tier inside the application (utf-8 encoded)
  • appTierId: Id to distinguish multiple services of one application tier (utf-8 encoded)
  • filterCallback: A callback for filter registration

Return Value:

  • This function returns the application handle of the registered application.
  • If the function fails, 0 is returned.

Remarks:

Your application must be registered before any events can be fired.

Usage Example

void RegisterSoftwareTelemetry()
{

  APMApplicationHandle g_applicationHandle = APMRegisterApplication(

    
"app.telemetry Software-Telemetry", "Demo", // appName, appId
    
"Backend Services”, "Repository",           // appTierName, -Id
    
NULL);                                      // filterCallback
}

Method APMUnregisterApplication (C/C++)Permanent link for this heading

Call APMUnregisterApplication at the end of your program to tell app.telemetry agent that your program lifetime ends now.

Syntax

APMDECL_EXTERN void APMFUNC APMUnregisterApplication(APMApplicationHandle application);

Parameters:

  • application: The handle of the application which gets unregistered.

Return Value:

This function does not return any value.

Remarks:

Unregistering all applications will stop the connection to the app.telemetry agent. As reconnecting takes time it is not recommended to unregister and reregister applications frequently.

Usage Example

void UnregisterSoftwareTelemetry()
{

    APMUnregisterAppl
ication(g_applicationHandle);
}

Method APMRegisterModule (C/C++)Permanent link for this heading

Call this function to register modules inside your application.

Syntax


APMDECL_EXTERN APMModuleHandle APMFUNC APMRegisterModule(

    
const char *modulename);

Parameters:

  • modulename Desired name of the APMModule (utf-8 encoded).

Return Value:

  • This function returns a handle which you need to associate events to their corresponding module.

Remarks:

  • Different modules are shown as different bars during the analysis.
  • Modules are registered per process and not per application, so each application in a process can use modules registered one in that process.
  • Modules are identified by their name. A registration of a module with a previously registered module name will return the same module handle as the first module registration as long as the module has not been unregistered.

Usage Example

//define constants for your events
#define APM_EVENT_PROCESS_REQUEST  100

#define APM_EVENT_GET_ARTICLE      101

#define APM_EVENT_GET_ARTICLE_DATA 102

APMApplicationHandle g_applicatione;
APMModuleHandle g_module;

void RepositoryRegisterEvents()
{
  
  APMModuleRegisterEvent(g_module, APM_EVENT_PROCESS_REQUEST, "Process Request", NULL);
  
  APMModuleRegisterEvent(g_module, APM_EVENT_GET_ARTICLE, "Get Article", NULL);
    APMModuleRegisterEvent(g_module, APM_EVENT_GET_ARTICLE_DATA, "GetArticle::length", "length(bytes)");
}

void RegisterSoftwareTelemetry()
{

    g_module = APMRegisterModule("Repository Handler");
  
  RepositoryRegisterEvents();
}

Method APMUnregisterModule (C/C++)Permanent link for this heading

Call APMUnregisterModule if you do not need to trace any more events tied with this module. Calling this function will clean up several internal processes.

Syntax

APMDECL_EXTERN void APMFUNC APMUnregisterModule(APMModuleHandle module);

Parameters:

  • module: Handle to the module which should get unregistered

Return Value:

This function does not return any value.

Remarks:

You may register and unregister modules any time but you should not reregister a single module frequently as the app.telemetry server has to keep all module registrations to be able to display all requests of a process correctly.

Usage Example

void CleanupModule(APMModuleHandle module)
{

  APMUnregisterModule(module);
}

Method APMModuleRegisterEvent (C/C++)Permanent link for this heading

It is required and important to register the events used in your application in order to get the correct event names and parameter descriptions as provided. The APMModuleRegisterEvent-function will tell the app.telemetry server a name for every event-ID and optionally parameter descriptions for the parameters used in the event calls.

Syntax

APMDECL_EXTERN void APMFUNC APMModuleRegisterEvent(
    APMModuleHandle module,

    APMEventId eventid,
    const char *description,

    const char *parameterdescription);

Parameters:

  • module: Module handle for which you register the event.
  • eventid: This is the id of the event you want to register.
  • description: The description of the event.
  • parameterdescription: Name of event parameters. If more parameters are used in one event, separate the parameter names by semi-colon (;). For example: "name;count;size"

Return Value:

This function does not return any value.

Remarks:

If an event has more than one parameter you need to separate the parameterdescription with semicolons (;).

Usage Example

void doRegisterEvents()
{

    //given that g_module is a valid handle of a registered module
  
  APMModuleRegisterEvent(g_module, 121, "Event 1", "int32;int64;String");
    APMModuleRegisterEvent(g_module, 122, "Event 2", "size;time stamp;User name");
}

Method APMRegisterFilterValue (C/C++)Permanent link for this heading

It is useful to register all possible filter values used in your application in order to get a list of available filters with descriptions in the client interface.

You may actively register filter values any time after registering the application by calling the APMRegisterFilterValue method.

To optimize filter registration in case enumeration of filter values is a costly action, the registration of filter values may be performed in the EnumAppFilterValuesCallback function, which is only called if needed (see “EnumAppFilterValuesCallback (C/C++)”).

Syntax

APMDECL_EXTERN void APMFUNC APMRegisterFilterValue(
  
APMApplicationHandle app,
    const char *value,

    const char *description);

Parameters:

  • app: The Handle of the APMApplication representing this application.
  • value: value is the raw filter value.
  • description: This is the description which is presented in the Client-User-Interface as filter.

Return Value:

This function does not return any value.

Remarks:

This function may be called inside the EnumAppFilterValuesCallback function which is initiated by the app.telemetry server.

Usage Example

void EnumAppFilterValuesCallback()
{

    APMRegisterFilterValue(g_applicationHandle, "raw filter 1", "Description for filter 1");
}

Context Handling Functions (C/C++)Permanent link for this heading

Method APMCreateContext (C/C++)Permanent link for this heading

Call APMCreateContext to create a new Software-Telemetry context. If the filter value matches a currently started session filter, logging is started for the current execution thread. Make sure to call APMReleaseContext when exiting the context. A context can be regarded as a complete request that is traced through several involved threads or modules. And the full context request has a duration that spans the interval from CreateContext to ReleaseContext.

Syntax

APMDECL_EXTERN void APMFUNC APMCreateContext(APMApplicationHandle app, const char *filtervalue);

Parameters:

  • app: The Handle of the APMApplication representing this application.
  • filtervalue: (optional) This value is used to match a filter of a started Software-Telemetry session. You should register filter values used by calling APMRegisterFilterValue (see “Method APMRegisterFilterValue (C/C++)”)

Return Value:

This function does not return any value.

Usage Example

void beginRequestProcessing(/* ... */)
{

  
  APMCreateContext(g_applicationHandle, "filter1");
    //...
  
  //proceed with application logic and fire events
    //...
  
  APMReleaseContext();
}

Method APMAttachContext (C/C++)Permanent link for this heading

Call APMAttachContext to restore the context acquired through APMGetContext in another thread or process (see “Passing Context” and “Method APMGetContext (C/C++)”).

Syntax

APMDECL_EXTERN void APMFUNC APMAttachContext(APMApplicationHandle app, const APMContext *context);

Parameters:

  • app: The Handle of the APMApplication representing this application.
  • context: The context which you want to attach to.

Return Value:

This function does not return any value.

Usage Example

void ContinueRequest(/* ... */, const APMContext *context, APMSyncMark *syncMark)
{

    APMAttachContext(g_applicationHandle, context);

    //...
    // continue with application logic and fire events

    //...
    APMGetSyncMark(syncMark);

    APMReleaseContext();

}

Method APMGetContext (C/C++)Permanent link for this heading

Call the APMGetContext-method to get a new context handle.

This context handle is used to synchronize different threads/processes/modules - this helps you track the control flow through a distributed environment. The acquired context handle has to be submitted (either by transmitting over the network or in another way) to the thread/process being called which associates the calling thread with itself by passing the context to the APMAttachContext-method.

Syntax

APMDECL_EXTERN int APMFUNC APMGetContext(APMContext *context);

Parameters:

  • context: APMGetContext creates a context at the location pointed to by context.

Return Value:

  • If the function succeeds, the return value is 1 and a context has been saved to the location which context pointed to.
  • If no context has been created, the return value is 0.

Usage Example

void initiateProcessing(/* ... */)
{

    APMCreateContext(g_applicationHandle, "filterstring");

    APMContext contex
t;
    APMGetContext(&context);

    //pass context to another thread, process on the same or a remote machine

   doRemote(/* data */, context);

    //do some local processing / wait for the remote processing to complete

    APMSyncMark syncMark;
    getRemoteResult(&syncMark);

    APMSetSyncMark(&syncMark);

    APMReleaseContext();

}

Method APMGetSyncMark (C/C++)Permanent link for this heading

Call the APMGetSyncMark-method to get a synchronization handle that can be passed to another thread/process/module to synchronize control flow.

The difference between a sync mark and a context is:

  • A context is used to associate with one request. It is created by the initiator and attached to by other threads/process belonging to the same request.
  • A sync mark is only a time synchronization handle between the different threads/processes which can be used several times to synchronize the control flow exactly (different systems may have different timestamps and different time precision).

Syntax

APMDECL_EXTERN int APMFUNC APMGetSyncMark(APMSyncMark *context);

Parameters:

  • context: APMGetSyncMark creates a sync mark at the location pointed to by context.

Return Value:

  • If the function succeeds, the return value is 1 and a sync mark has been saved to the location which context pointed to.
  • If no sync-mark has been created, the return value is 0.

Usage Example

void doRemote(/* ... */, APMContext *context)
{

    APMAttachContext
(g_applicationHandle, context);

    //application logic, events, ...

    APMSyncMark syncMark;
    APMGetSyncMark(&syncMark);

    sendResultBack(/* ... */, syncMark);

    APMReleaseContext();
}

Method APMSetSyncMark (C/C++)Permanent link for this heading

Call APMSetSyncMark to pass a sync mark you got from APMGetSyncMark for synchronizing the sequence of events (see “Synchronizing Timeline with SyncMarks” and “Method APMGetSyncMark (C/C++)”).

Syntax

APMDECL_EXTERN void APMFUNC APMSetSyncMark(const APMSyncMark *context);

Parameters:

  • context: The sync mark which you want to sync with.

Return Value:

This function does not return any value.

Usage Example

void initiateProcessing(/* ... */)
{

  
  APMCreateContext(g_applicationHandle, "filterstring");
  
  APMContext context;
  
  APMGetContext(&context);

    //pass context to another thread, process or a remote server

    doRemote(/* data */, context);

    //do some local processing/wait for the remote processing to complete
    APMSyncMark syncMark;
  
  getRemoteResult(&syncMark);
    APMSetSyncMark(&syncMark);
  
  APMReleaseContext();
}

Method APMReleaseContext (C/C++)Permanent link for this heading

Call APMReleaseContext to finish logging and to flush logged information to the app.telemetry infrastructure.
Make sure to call APMReleaseContext when exiting the context (when the request is finished).

Syntax

APMDECL_EXTERN void APMFUNC APMReleaseContext();

Parameters:

This function does not take any arguments.

Return Value:

This function does not return any value.

Remarks:

  • If you don't call APMReleaseContext the request keeps the running status until the request-timeout has been reached.

Usage Example

void doRemote(/* ... */, APMContext *context)
{

  APMAttachContext(g_applicationHandle, context);

  //application logic, events, ...

  APMSyncMark syncMark;

  APMGetSyncMark(&syncMark);

  sendResultBack(/* ... */, syncMark);

  APMReleaseContext();

}

Method APMDetachThread (C/C++)Permanent link for this heading

Call the APMDetachThread-method when processing of a particular request is suspended and will be resumed later in this or another thread in the same process. Pass the handle returned by this method to the APMAttachThread-method to resume processing.

This functionality is in particular useful in queuing systems, where a large number of requests will be queued and processed by a small number of worker threads asynchronous to the initial request. Using the APMDetach-/APMAttachThread methods you can follow the request through the process and even measure the time spent in the queue, even if a different thread continues processing.

Syntax

APMDECL_EXTERN int APMFUNC APMDetachThread(APMTransactionHandle *handle);

Parameters:

  • handle: APMDetachThread generates an id (64bit) that uniquely identifies the current state of the request.

Return Value:

  • If the function succeeds, the return value is 1 and a context has been saved to the location which context pointed to.
  • The function will return 0 in case the library is not available or if no request has been started using APMCreateContext and/or APMAttachContext.

Remarks:

Be careful to use APMDetachThread and APMAttachThread in a balanced way. APMDetachThread will store the current state of the request in memory and APMAttachThread will remove the information from memory while restoring the request state. So calls to APMDetachThread lacking a continuation will leak memory and will leave the request in a "running" state. Multiple calls to APMAttachThread with the same handle will not have an effect, because the request state is only available to the first call to APMAttachThread.

Usage Example

struct TaskData
{

  
//...
  
  APMTransactionHandle tx;
    //...
}

void initiateProcessing(/* ... */)
{

    APMCreateContext(g_applicationHandle, "filterstring");

    TaskData *task = new TaskData();

    APMEvent(myModule, APM_EVENT_ENTER_TASK_TO_QUEUE, APM_EVENT_LEVEL_NORMAL, APM_FLAG_ENTER);

    APMDetachThread(&task->tx);

    queueTask(task);

}

void processTask(TaskData *task)
{

    APMAttachThread(task->tx);

    APMEvent(myModule, APM_EVENT_REMOVE_TASK_FROM_QUEUE, APM_EVENT_LEVEL_NORMAL, APM_FLAG_LEAVE);

    // process work

    delete task;
    APMReleaseContext();

}

Method APMAttachThread (C/C++)Permanent link for this heading

Call the APMAttachThread-method when processing of a particular request is resumed after being suspended in this or another thread of the same process. Pass the handle returned by APMDetachThread-method to restore the recorded state of the request.

This functionality is in particular useful in queuing systems, where a large number of requests will be queued and processed by a small number of worker threads asynchronous to the initial request. Using the Detach-/AttachThread methods you can follow the request through the process and even measure the time spent in the queue, even if a different thread continues processing.

Syntax

APMDECL_EXTERN void APMFUNC APMAttachThread(APMTransactionHandle handle);

Parameters:

  • handle: APMAttachThread uses the handle generated by APMDetachThread to identify the current state of the request.

Remarks:

See “Method APMDetachThread (C/C++)

Usage Example

struct TaskData
{

  
//...
  
  APMTransactionHandle tx;
  
  //...
}

void initiateProcessing(/* ... */)
{
    APMCreateContext(g_applicationHandle, "filterstring");

    TaskData *task = new TaskData();

    APMEvent(myModule, APM_EVENT_ENTER_TASK_TO_QUEUE, APM_EVENT_LEVEL_NORMAL, APM_FLAG_ENTER);

    APMDetachThread(&task->tx);

    queueTask(task);

}

void processTask(TaskData *task)
{

    APMAttachThread(task->tx);

    APMEvent(myModule, APM_EVENT_REMOVE_TASK_FROM_QUEUE, APM_EVENT
_LEVEL_NORMAL, APM_FLAG_LEAVE);

    // process work

    delete task;
    APMReleaseContext();

}

Event Functions (C/C++)Permanent link for this heading

The four APMEvent functions log Software-Telemetry data. They have the first 4 parameters in common and vary in the options to pass additional parameters.

The common parameters are:

Method APMEvent (C/C++)Permanent link for this heading

Call the APMEvent function to log an event without parameters. Only the event-ID and the flags define the representation of the event that will be displayed with the registered event name for the used id.

Syntax

APMDECL_EXTERN void APMFUNC APMEvent(
    APMModuleHandle module,

    APMEventId eventid,

    APMEventLevel level,

    APMEventFlags flags);

Parameters:

Return Value:

This function does not return any value.

Usage Example

    //steps required before logging events:
    // * application registered,

    // * module is a handle to a registered module,

    // * id is the id of a registered event,

    // * a context has been created or attached

    APMEvent(module, id, APM_EVENT_LEVEL_DEBUG, APM_FLAG_NONE);

    //...

Method APMEventArgs (C/C++)Permanent link for this heading

Use APMEventArgs to log an event with various parameters, which must be passed in a predefined format.

Syntax

APMDECL_EXTERN void APMFUNC APMEventArgs(
    APMModuleHandle module,

    APMEventId eventid,

    APMEventLevel level,

    APMEventFlags flags,

    UInt8 paramCount,

    APMParameterType *paramTypes,

    void *paramValues,

    unsigned paramValueSize);

Parameters:

  • The APMEventArgs function has the 4 base parameters (see “Event Functions (C/C++)”).
  • paramCount: The number of parameters you want to pass to this function.
  • paramTypes: This is an array containing the types of the parameters. The size of the array is equal to paramCount.
  • paramValues: This pointer points to the continuous memory region containing the parameters.
  • paramValueSize: This is the size of the memory region containing the parameter values (paramValues).

Return Value:

This function does not return any value.

Usage Example

    //steps required before logging events:
    // * application registered,

    // * module is a handle to a registered module,

    // * id is the id of a registered event,

    // * a context has been created or attached

    APMParameterType types[3] = {APM_PARAMETERTYPE_INT32,

        APM_PARAMETERTYPE_INT64, APM_PARAMETERTYPE_STRING};

    UInt32 par32 = 4;
    UInt64 par64 = 2147483698004;

    char parstr[] = "genericParam4";
    unsigned int size = (unsigned int)(sizeof(UInt32) + sizeof(UInt64) + sizeof(UInt16) + strlen(parstr));

    void *mem = calloc(1, size);
    if(mem) {

      char *bptr = (char *)(mem);

      *(UInt32 *)(bptr) = par32;

      bptr += sizeof(UInt32);

      *(UInt64 *)(bptr) = par64;

      bptr += sizeof(UInt64);

      *(UInt16 *)(bptr) = (UInt16)strlen(parstr);

      bptr += sizeof(UInt16);

      strncpy(bptr, parstr, strlen(parstr));

      APMEventArgs(module, id, APM_EVENT_LEVEL_DEBUG, APM_FLAG_NONE, 3, types, mem, size);
      free(mem);

    }

    //...

Method APMEventParam (C/C++)Permanent link for this heading

Call the APMEventParam-method to log events with a generic parameter structure - with any number and combination of textual (string) values and integer values (32- and 64-bit).
To use the APMEventParam-method you have to initialize an APMParamHandle. With a few helper methods you can add values to this parameter object (see “Parameter Functions (C/C++)”) and use the parameter object in the event function to be logged. Do not forget to free the parameter handle with APMParamFree (see “Method APMParamFree (C/C++)”).

Syntax

APMDECL_EXTERN void APMFUNC APMEventParam(APMModuleHandle module,
    APMEventId eventid,

    APMEventLevel level,

    APMEventFlags flags,

    APMParamHandle param);

Parameters:

  • The APMEventArgs function has the 4 base parameters (see “Event Functions (C/C++)”).
  • param: This is the handle you obtained from a call to APMParamInit.

Return Value:

This function does not return any value.

Usage Example

    //steps required before logging events:
    // * application registered,

    // * module is a handle to a registered module,

    // * id is the id of a registered event,

    // * a context has been created or attached

    APMParamHandle ph;

    ph = APMParamInit();

    APMParamAdd32(ph, 3);

    APMParamAdd64(ph, 2147483698003);
    APMParamAddString(ph, "genericParam3");

    APMEventParam(module, 123, APM_EVENT_LEVEL_DEBUG, APM_FLAG_NONE, ph);

    APMParamFree(ph);

    //...

Method APMEventStr (C/C++)Permanent link for this heading

Use APMEventStr to log an event with an additional string value as parameter.

Syntax

APMDECL_EXTERN void APMFUNC APMEventStr(
  APMModuleHandle module,

  APMEventId eventid,

  APMEventLevel level,

  APMEventFlags flags,

  const char *param);

Parameters:

  • The APMEventArgs function has the 4 base parameters (see “Event Functions (C/C++)”).
  • param: Pointer to null-terminated, utf8-encoded string. The maximum string length allowed is 32768 Byte.

Return Value:

This function does not return any value.

Usage Example

    //steps required before logging events:
    // * application registered,

    // * module is a handle to a registered module,

    // * id is the id of a registered event,

    // * a context has been created or attached

    APMEventStr(module, id, APM_EVENT_LEVEL_DEBUG, APM_FLAG_NONE, "stringparam1");

    //...

Parameter Functions (C/C++)Permanent link for this heading

The parameter functions provide a way to pass up to 255 parameters to an APMEventParam call.

Allocate an APMParamHandle by calling APMParamInit. Add parameters calling APMParamAdd32, APMParamAdd64 or APMParamAddString. Pass the APMParamHandle to the APMEventParam function and finally call APMParamFree to free associated memory.

Usage Example

    //steps required before logging events:
    // * application registered,

    // * module is a handle to a registered module,

    // * id is the id of a registered event,

    // * a context has been created or attached

    APMParamHandle ph;

    ph = APMParamInit();
    APMParamAdd32(ph, 3);

    APMParamAdd64(ph, 2147483698003);

    APMParamAddString(ph, "genericParam3");

    APMEventParam(module, id, APM_EVENT_LEVEL_DEBUG, APM_FLAG_NONE, ph);

    APMParamFree(ph);

    //...

Method APMParamInit (C/C++)Permanent link for this heading

APMParamInit is used to initialize an APMParamHandle.

Syntax

APMDECL_EXTERN APMParamHandle APMFUNC APMParamInit();

Parameters:

This function does not take any arguments.

Return Value:

  • This function returns a handle which you can use to add parameters and pass to APMEventParam.

Remarks:

Method APMParamAdd32 (C/C++)Permanent link for this heading

Call APMParamAdd32 to add a 32 bit unsigned integer to the parameter handle.

Syntax

APMDECL_EXTERN void APMFUNC APMParamAdd32(APMParamHandle param, UInt32 value);

Parameters:

  • param: APMParamHandle obtained from APMParamInit.
  • value: The value which you want to add.

Return Value:

This function does not return any value.

Method APMParamAdd64 (C/C++)Permanent link for this heading

Call APMParamAdd64 to add a 64 bit unsigned integer to the parameter handle.

Syntax

APMDECL_EXTERN void APMFUNC APMParamAdd64(APMParamHandle param, UInt64 value);

Parameters:

  • param: APMParamHandle obtained from APMParamInit.
  • value: The value which you want to add.

Return Value:

This function does not return any value.

Method APMParamAddString (C/C++)Permanent link for this heading

Call APMParamAddString to add a string to the parameter handle.

Syntax

APMDECL_EXTERN void APMFUNC APMParamAddString(APMParamHandle param, const char *value);

Parameters:

  • param: APMParamHandle obtained from APMParamInit.
  • value: The value which you want to add. The maximum length of the utf-8 encoded string is 32768 Byte.

Return Value:

This function does not return any value.

Method APMParamFree (C/C++)Permanent link for this heading

Call APMParamFree to release the memory allocated for the parameters created by APMParamInit.

Syntax

APMDECL_EXTERN void APMFUNC APMParamFree(APMParamHandle param);

Parameters:

  • param: APMParamHandle created by APMParamInit.

Return Value:

This function does not return any value.

Remarks:

Use this function to free internal memory associated to the parameters.

Fabasoft app.telemetry Button (C/C++)Permanent link for this heading

Method APMReport (C/C++)Permanent link for this heading

Call APMReport to create a new feedback report.

The filter value will be matched to the description using the registered filter values. Use the textual description of the feedback entered by the user or generated by the application to identify the report session later again.

If a log pool exists for the current application, the latest requests where the APMCreateContext filtervalue parameter matches the filtervalue passed to the APMReport function, will be associated with the feedback.

Syntax

APMDECL_EXTERN void APMFUNC APMReport(
    APMApplicationHandle app,

    const char *filtervalue,

    const char *reportkey,

    const char *description);

Parameters:

  • app: The Handle of the APMApplication representing this application.
  • filtervalue: filtervalue to match requests with.
  • reportkey: A key value may be generated by the calling application to associate further descriptions to a feedback. If empty, a new feedback report will be generated on each call and no further information may be attached to the feedback.
  • description: Textual description of the feedback entered by the user or generated by the application. The maximum length of the description is 32768 Bytes.

Return Value:

This function does not return any value.

Remarks:

  • Since version 2009 Fall Release (4.3) the key value is used to associate further descriptions to a feedback.
  • In previous versions each call of this function had generated a new feedback report.

Usage Example

    //application logic, context created / attached
    APMReport(g_applicationHandle, "filter1", null, "Description entered by the user / application generated description");

Method APMReportValue (C/C++)Permanent link for this heading

Call APMReportValue to add a key/value pair to an existing report.

Syntax

APMDECL_EXTERN void APMFUNC STRUDLReportValue(
    APMApplicationHandle app,

    const char *reportkey,

    const char *key,

    const char *value);

Parameters:

  • app: The Handle of the APMApplication representing this application.
  • reportkey: reportkey matches the reportkey of the APMReport function to associate the value with the report session.
  • key: A key describes the meaning of the value. Only one value can be associated to a single key in one report session.
  • value: Text (max. 32 kBytes).

Return Value:

This function does not return any value.

Usage Example

    //application logic, context created / attached
    APMReport(g_applicationHandle, "filter1", "abc", "Description entered by the user / application generated description");

    APMReportValue(g_applicationHandle, "abc", "firstname", "John");

    APMReportValue(g_applicationHandle, "abc", "lastname", "Doe");

Method APMReportContent (C/C++)Permanent link for this heading

Call APMReportContent to associate content with an existing report.

Syntax

APMDECL_EXTERN void APMFUNC APMReportContent(
    APMApplicationHandle app,

    const char *reportkey,

    const char *filename,

    const void *data,

    UInt64      size);

Parameters:

  • app: The Handle of the APMApplication representing this application.
  • reportkey: reportkey matches the reportkey of the APMReport function to associate the content with the report session.
  • filename: A filename describing the content of the file. (max. 256 Bytes)
  • data: Pointer to a binary data.
  • size: Size of the data content.

Return Value:

  • This function does not return any value.

Usage Example

    std::string xmlContent = "...";
    //application logic, context created / attached

    APMReport(g_applicationHandle, "filter1", "abc", "Description entered by the user / application generated description");

    APMReportValue(g_applicationHandle, "abc", "firstname", "John");

    APMReportValue(g_applicationHandle, "abc", "lastname", "Doe");

    APMReportContent(g_applicationHandle, "abc", "parameter.xml", xmlContent.data(), xmlContent.length())

Method APMReportFile (C/C++)Permanent link for this heading

Call APMReportFile to associate a file with an existing report.

Syntax

  APMDECL_EXTERN void APMFUNC APMReportFile(
    APMApplicationHandle app,

    const char *reportkey,

    const char *filename,

    FILE *filehandle);

Parameters:

  • app: The handle of the APMApplication representing this application.
  • reportkey: reportkey matches the reportkey of the APMReport function to associate the value with the report session.
  • filename: A filename describing the content of the file. (max. 256 Bytes)
  • filehandle: File pointer that has been opened for reading.

Return Value:

This function does not return any value.

Remarks:

  • Until version 2010 Spring Release the filhandle has been declared as HANDLE under Microsoft Windows. This has been changed to a FILE pointer for consistency and dependency reasons since version 2010 Summer Release.

Usage Example

    //application logic, context created / attached
    APMReport(g_applicationHandle, "filter1", "abc", "Description entered by the user / application generated description");

    APMReportValue(g_applicationHandle, "abc", "firstname", "John");

    APMReportValue(g_applicationHandle, "abc", "lastname", "Doe");

    FILE *f = fopen("/tmp/parameter.xml", "r");

    APMReportFile(g_applicationHandle, "abc", "parameters.xml", f);

    fclose(f);

Status Functions (C/C++)Permanent link for this heading

Method APMHasActiveContext (C/C++)Permanent link for this heading

Call APMHasActiveContext to test, if a software-telemetry session is active for some logging level. This information should be used to avoid costly operations preparing parameters for events that are currently not logged.

Syntax

APMDECL_EXTERN int APMFUNC APMHasActiveContext(APMEventLevel level);

Parameters:

  • level: The event level of the event you prepare parameters for.

Return Value:

  • The return value is non-zero if the event will be logged.

Usage Example

void processRequest()
{

    APMCreateContext(g_applicationHandle, "filter value");

    //application logic

    if (0 != APMHasActiveContext(APM_EVENT_LEVEL_DEBUG))
    {

        //prepare parameters, set events,...

    }

    APMReleaseContext();

}

Method APMIsConnected (C/C++)Permanent link for this heading

Call APMIsConnected to test, if the application has successfully registered to an app.telemetry agent.

Syntax

APMDECL_EXTERN int APMFUNC APMIsConnected();

Parameters:

This function does not take any arguments.

Return Value:

  • If the application is not connected to an app.telemetry agent this function returns zero.
  • If the function is successfully connected, the return value is one.

Usage Example

bool checkConnection()
{

    return (1 == APMIsConnected());

}

Method APMIsCompatible (C/C++)Permanent link for this heading

Call APMIsCompatible to test, if the application was linked with a version that is compatible with the dynamically loaded library.

Syntax

APMDECL_EXTERN int APMFUNC APMIsCompatible(UInt32 size, char *message);

Parameters:

  • size: Size in Bytes of the memory region where the second parameter points. Allocate at least 200 Bytes to get the full version message.
  • message: Pointer to a memory region of the size specified in parameter 1. A descriptive text with an optional product name and version number will be stored in the allocated memory region.

Return Value:

  • This function returns non-zero if the used versions are compatible.

Usage Example

bool checkCompatible()
{

  char version[300];

  return (FALSE != APMIsCompatible(300, version));

}