ITrack/MySQL Message Framework

The MySQL Message Framework is used to create a connection to a message repository. The message repository allows the calling code to create and receive messages from other processes.

General

The MySQL Message Framework requires the following:

• The ability to connect to an external MySQL server.

The MySQL Message Framework is an ISoft internal tool; it is used at developer discretion and cannot be added on-the-fly via extensions.

Usage

Add the MySQL Message Framework project to your workspace and its .lib file included in the project that you wish to use it in. Add this include line to your source: #include "../../Libraries/include/libITMySQLMessageFramework.h"

Read Code to see how to use each instance.

Code

Each message pipe requires an object. The object is persistent, and should be put into a thread that has a sleep cycle of some variety.

Creating a new Message Framework object

Create a new ITMySQLMessageFramework object:

• ITMySQLMessageFramework* itMessageFramework = new ITMySQLMessageFramework(<active connection handle to the message repository>, <service type enum>, <service id unique int>, <service handle if one already exists>, <one or more flags for type> OR ITMySQLMessageFramework::GetStandardFlags())
• Call IsHeartbeatActive() to make sure your heartbeat is available
• Call IsMessagePipeActive() to make sure your message pipe is available (if you don't have a service handle, it won't be)

Using Heartbeat functionality

• Whenever you deem necessary, call itMessageFramework->TriggerHeartbeat(<optional status>)
• If it's your first heartbeat, you can now call itMessageFramework->GetHandle() to get the service's handle. This is necessary for posting/receiving messages

Using Message Pipe functionality

If you have a new handle and the pipe isn't connected, call:

• itMessageFramework->InitMessagePipe(itMessageFramework->GetHandle());
• Check IsMessagePipeActive() to make sure it worked

To check for new messages given to your process, call:

• itMessageFramework->PumpMessages()
• while (itMessageFramework->GetNextMessage(message)) {...} will give you each message you received

Submitting a message

• Create a new ITMySQLMessage object
• message.SetRecipient(<recipient handle>) if you know the recipient. Leave blank if you don't
• message.SetName(<message type name>) if you didn't provide it in the constructor
• message.AddInputData(...) and message.AddOutputData(...) to attach your message data
• itMessageFramework->SubmitMessage(message);

Responding to a message

• Use the message you got from itMessageFramework->GetNextMessage(message)
• message.SetName(<message response type name>) if you want to change the message type
• message.AddOutputData(...) to add your response data if any
• itMessageFramework->SubmitResponse(message)

Caveats

Errors that occur will most likely be ITSQLError objects that get thrown.

You must create and handle your own MySQL connection object.

Message Framework objects are NOT thread-safe. Separate objects may be used in separate threads, though.

Direct Database Manipulation

You are able to use this message framework by directly manipulating the database. This can be useful in scripting and debugging.

Creating a Message

• SELECT `f_message_init`(<recipient handle>);
• For each data element:
  • SELECT `f_message_attach_data`(<message id>, <'Input'|'Output'>, '', '');
• SELECT `f_message_post`(<message id>, '<message type>', <has inputs, 'True'|'False'>, <expects response, 'True'|'False'>);

At this point, the message will be available in v_messages for receipt.

Responding to a Message

• View available messages and their data using:
  • SELECT * FROM `v_messages` LEFT JOIN messagedata USING (`messageid`);
    • If you have a handle, add : WHERE `handle` = '<handle>'
• SELECT `f_message_claim`(<message id>);
• For each data element you wish to add:
  • SELECT `f_message_attach_data`(<message id>, 'Output', '', '');
• SELECT `f_message_respond`(<message id>);

At this point, the message will be available in v_responses for any listeners if the message expects a response, and the message will be closed and removed otherwise.

Closing a Message

• SELECT * FROM `f_message_close`(<message id>);

This action can be done at any time, and will only cause issue if you close someone else's message after they've copied the message, but before they've claimed it