ARDecodeAlertMessage

Important

You can continue to use C APIs to customize your application, but C APIs are not enhanced to support new capabilities provided by Java APIs and REST APIs.

Description

Decodes a formatted alert message and returns the component parts of the message to the alert client.

Synopsis

#include "ar.h"
#include "arerrno.h"
#include "arextern.h"
#include "arstruct.h"

int ARDecodeAlertMessage(
  ARControlStruct *control,
  unsigned char *message,
  unsigned int messageLen,
  ARTimestamp *timestamp,
  unsigned int *sourceType,
  unsigned int *priority,
  char **alertText,
  char **sourceTag,
  char **serverName,
  char **serverAddr,
  char **formName,
  char **objectId,
  ARStatusList *status)

Input arguments

control

The control record for the operation. It contains information about the user requesting the operation, where that operation is to be performed, and which session is used to perform it. The user and server fields are required.

message

An alert message buffer received by the client through its sockets communication with the server. The buffer is not null-terminated.
The method for receiving the message from the socket is as follows:

Read at least the first 8 bytes that comprise the message header. The first 4 bytes are a message header identifier and the second 4 bytes are the length of the entire message in network byte order.
Using the ntohl() system function, convert the 4-byte message length into the host integer format.
Using the length, determine if the entire message has been received. If it has not, continue to receive data on the socket until the entire length of the message has arrived.
Pass the entire message buffer, including the header, as this parameter.

messageLen

The byte length of the alert message buffer supplied in the message parameter.

Return values

timestamp

The time that the alert event or indicator was created. Specify NULL for this parameter if you do not want to retrieve the time stamp.

sourceType

A value that identifies the source of the alert. The possible values are:

Specify NULL if you do not want to return the source type. * AR SystemAlert is no longer shipped with AR System.

priority

A relative value that represents the priority for this alert. The range of acceptable values is between 0 and 10. Specify NULL if you do not want to return the priority.

alertText

The text that the alert contains. Specify NULL if you do not want to return the text. If you do not specify NULL, you must free the returned memory buffer.

sourceTag

A string that identifies the source of the alert. Specify NULL if you do not want to return the source tag. If you do not specify NULL, you must free the returned memory buffer.

serverName

The name of the server that is the source of the alert. A value of @ indicates the current server. Specify NULL if you do not want to return the server name. If you do not specify NULL, you must free the returned memory buffer.

serverAddr

The server IP address that the client expects. This is usually the IP address of the server named in the serverName parameter, except in the case where a load balancer works with the AR System server or there are multiple servers accessing the same database. Specify NULL if you do not want to return the server address. If you do not specify NULL, you must free the returned memory buffer.

formName

The name of the form that is the source of the alert. For Flashboards, this is the name of the Flashboard that generated the alert. Specify NULL if you do not want to return this value. If you do not specify NULL, you must free the returned memory buffer.

objectId

The identifier for the object. For AR System, this value is a special entry ID format. For a join form, the AR System server concatenates all entry IDs and precedes them with a two-character count.
For example, 02000000000012345000000000023456.

For non-join forms, the AR System server precedes the entry IDs with a two-character count (01000000000098765). For Flashboards, this value is the name of the Flashboardsalert. Specify NULL if you do not want to return this value. If you do not specify NULL, you must free the returned memory buffer.

status

A list of zero or more notes, warnings, or errors generated from a call to this function. For a description of all possible values, see Error-checking.