HS MSG C/C++ Messaging Library




Message Oriented Middleware in C/C++ for Windows, Linux, MAC OSX, iOS

Overview

HS MSG is a C/C++ messaging library (message oriented middleware) for communication between threads of the same process and between different processes on the same or on different computers. HS MSG C/C++ messaging SDK runs on Windows, Linux, MAC OSX, iPhone iOS

HS MSG is supplied with full C source code. The use of HS MSG is Royalty Free.

HS MSG currently includes the C source for the following platforms:

  Windows    Linux    Apple MAC OS X    Apple iPhone iOS



Features

  • Simple C interface for message sending and reception
  • Message reception asynchronously (poll method) using HsMsgPollQueue()
  • Message sending asynchronously (HsMsgPostMessage()) or synchronously (HsMsgSendMessage())
  • Capability to send and receive messages containing large data buffers (segmentation, re-assembly re-transmissions are handled by internal protocol)
  • Cross platform C library for Windows, Unix/Linux, MAC OS X, iOS
  • C Source code suitable for porting to embedded devices
  • Thread safe
  • Simultaneous messages sending and reception, multiple concurrent message sessions are supported
  • Deliver messages to different queues created either by different distributed computers or by differnet processes on the same computer or to local queues belonging to the same process
  • Reliable message transport protocol implemented over UDP


How It Works

First user application calls HsMsgInit() initialization function to initialize the HsMsg library

Then the user application can create a message "Inbox" for receiving messages from other peers. A parameter to HsMsgCreateInbox function is an IP port number on which HsMsg shall receive messages

After that the application call create one or more message queues associated with this inbox, calling HsMsgAddQueue(). Each queue is given a string name. The remote (or local) entities will send messages to the inbox and the specific queue name

In order to allow HsMsg to drive internal timing, reception and processing of data from underlying transport layer, the application must periodically call HsMsgTick()

Once at least one queue has been created, an applicatin can poll the queue for messages by periodically calling HsMsgReadQueue, specifying the inbox handle, the queue handle and a pointer to the message structure

To send messages without requiring the result, the application calls HsMsgPostMessage(), specifying the inbox handle on which the message will go out, the destination address, which consists of the remote IP address and port and the destination queue name. HsMsgPostMessage() returns immediately and the messages sending is handled automatically by HsMsg in the background

To send messages syncronously the application calls HsMsgSendMessage(), this function does not return until the message has been fully delivered to the destination queue or a permanent (unrecoverable) error occured.

HsMsg library internally implements reliable transmission of the message content over UDP, dealing with message segmentation, re-assembly, multiplexing and de-multiplexing, re-transmissions, etc.

When finished working with the library (typically before exit) the application calls HsMsgCleanUp() to de-initialize the library

API Summary

  • HsMsgInit()
  • HsMsgCleanUp()
  • HsMsgCreateInbox()
  • HsMsgAddQueue()
  • HsMsgTick()
  • HsMsgReadQueue()
  • HsMsgPostMessage()
  • HsMsgSendMessage()
  • HsMsgRemoveQueue()
  • HsMsgDestroyInbox()
  • HsMsgCleanUp()


Development Tools

The HS MSG library is provided with the following project build environments:

  • Microsoft Visual Studio 6.0
  • Microsoft Visual Studio 2005
  • Microsoft Visual Studio 2010
  • MAX OS X XCode
  • Linux gcc makefile


HS MSG Library Architecture

The library includes several copmonents which link to customer's application:




HS MSG Library File Structure

Core HS MSG Library

  • hsmsg.c (43 functions, 1363 lines)
  • hsmsg.h (154 lines)
  • hsmsg_if.h (119 lines)

UDP / TCP Socket interface library

  • hssock.c (41 functions, 1584 lines)
  • hssock.h (148 lines)
  • hssock_if.h (133 lines)

HS MSG Sample apps

  • Hsmsg_chat.c (Linux and MAC OS X): (180 lines)
  • Hsmsg_chat.c (Windows): (211 lines)
  • Recvfile.c (Linux and MAC OS X) (137 lines)
  • Recvfile.c (Windows) (135 lines)
  • Sendfile.c (Linux and MAC OS X) (147 lines)
  • Sendfile.c (Windows) (145 lines)

Limitations in the evaluation version

The evaluation version of HS MSG Library has the following limitations
  • Windows version displays a message box requiring user clicking OK before initializatoin continues.
  • Linux and MAX OS X versions display Hillstone Software copyright information at startup.
  • Total number of messages allowed to send is limited to 100. After that the send function returns failure code -18. The application must re-start to reset this count.

Sample Applications

HS MSG C/C++ library comes with several sample applications for Windows, Linux, MAC OS X



Customization

Hillstone Software provides additional services for customization, porting and integration of the library code to better suit the needs of your products