Push4Free

Let's know the basic flow of delivering real-time messages with iPush first.

1. connect and login

For using iPush Server (server) to send or receive real-time messages, the applications (clients) must connect and login to iPush Server first. A TCP or UDP connection can be established between client and server.

- client function call sample:

  ipushTCPConnect(SERVER, PORT, GROUP, PRODUCT, USERID, PASSWORD)

2. subscribe subject (receiver)

The receiver must subscribe for one or more subjects before it can receive any message pushed from server.

- client function call sample:

  ipushSubSubject(SUBJECT_NAME)

3. publish message (sender)

The sender publishes a message with specific subject to server.

- client function call sample:

   ipushSendNPSubjectData(SUBJECT_NAME, MESSAGE)

4. on message handling (receiver)

Once server receives the message, it will push the message to the client has subscribed the specified subject in real-time fashion. Receiver should handle the message in the implemented callback function as event-trigger matter.

- client callback function sample:

   onSubjectMessage = function(ev) {
        trace("subject=" + ev.subject + ", message=" + ev.message);
   }

iPush supports both TCP and UDP (over IP) protocols. Developer can determinate which protocol would be used by calling different function call.

Relative function calls

Connect and Login to server:

• ipushTCPConnect()
• ipushUDPConnect()

iPush supports two messaging models: publish/subscribe and point-to-point.

1. publish/subscribe (Pub/Sub)

Pub/Sub messaging model can achieve one-to-many message broadcasting. Once server receives a specific subject message, it will push the message to all of the clients who have subscribed the exact subject.

Relative function calls

Subscribe/Unsubscribe subject:

• ipushSubSubject()
• ipushUnsubSubject()
• ipushSubDSubject()
• ipushUnsubDSubject()

Publish subject (Pub/Sub) message:

• ipushSendNPSubjectData()
• ipushSendPSubjectData()

2. point-to-point (P2P)

P2P messaging model (also called Queuing) can achieve one-to-one message dispatching. Once server receives a specific message, it will push the message to one of the clients who have subscribed the exact subject. Think about the process of purchase order handling, any order should not be received by two or more staff. For client load-balancing, server will dispatch the coming messages in round-robin way.

Relative function calls

Subscribe/Unsubscribe subject:

• ipushSubSubject()
• ipushUnsubSubject()
• ipushSubDSubject()
• ipushUnsubDSubject()

Publish subject (P2P) message:

• ipushSendNPQueueData()
• ipushSendPQueueData()

!! The publish(send) function call will determinate whether a message is applied to Pub/Sub or P2P model.

iPush supports two types of message addressing: channel addressing and subject addressing.

Message addressing means that every message delivered by iPush should be designated on a specific channel ID or subject name.

1. channel addressing

A channel ID is a 4-byte string which can be represented as an ASCII character string or a hex string. For example, channel ID 1234 (in ASCII) can also be represented as 0x31323334 (in Hex).

Channel addressing provides more efficiency for exchanging messages since it takes much lower overhead than subject addressing and is easy to program (only publish/subscribe messaging model is supported with channel addressing).

Relative function calls

Subscribe/Unsubscribe channel:

• ipushSubChannel()
• ipushUnsubChannel()

Publish channel (Pub/Sub) message:

• ipushSendChannelData()

Receiving channel message callback function:

• SetChannelData() - in ActiveX Control APIs
• OnSetChannelData() - in .NET Framework and .NET Compact Framework APIs
• onChannelMessage() - in Java and Flash AS2 APIs
• onChannelData() - in Linux C and Windows DLL APIs

2. subject addressing

A subject name is a dot-separated character string which is much more readable than channel ID. For example, you can use ICE.marketing to represent the subject name of a message . The maximum length of a valid subject name is 223-byte (but may be various by different API implementations). However, longer subject name will introduce more network overhead. Alphanumeric characters, 0-9, a-b, A-B, and '_' are accepted characters for defining a subject name and it is case sensitive.

Subject addressing provides many more additional features than channel addressing, like message queuing (Point-to-Point), persistent publishing, durable subscription, time-to-live, QoS, connection ID, etc. Subject name is much more meaningful to understand than channel ID since you can use almost any string to compose a subject name. Although, subject addressing messages have to pay more overheads for these great features but you don't have to worry about the efficiency of subject message delivery in almost applications.

We strongly recommand you program iPush with the subject addressing in general cases.

Relative function calls

Subscribe/Unsubscribe subject:

• ipushSubSubject()
• ipushUnsubSubject()
• ipushSubDSubject()
• ipushUnsubDSubject()

Publish subject message:

• ipushSendNPSubjectData()
• ipushSendPSubjectData()
• ipushSendNPQueueData()
• ipushSendPQueueData()

Receiving subject message callback function:

• SetSubjectData() - in ActiveX Control APIs
• OnSetSubjectData() - in .NET Framework and .NET Compact Framework APIs
• onSubjectMessage() - in Java and Flash AS2 APIs
• onSubjectData() - in Linux C and Windows DLL APIs

!! The publish(send) function call will determinate whether a message is addressed in channel or subject. And the receiver should implement different callback functions to handle the channel or subject addressing messages received.

When a message is sent with subject addressing, the sender can designate whether the message is persistent or non-persistent by calling different sending functions.

The entity which receives a persistent message should send an acknowledgement back to the sender as a receipt. There are two occasions for the acknowledgement getting fired:

1. From iPush Server to message sender.
2. From message receiver to iPush Server.

So far, the acknowledgement is automatically triggered and handled between iPush Server and client API.

Messaging with acknowledgement means higher quality of message delivery. Actually, persistent messaging is an important feature of guaranteed delivery (another one is durable subscription).

On the contrary, non-persistent would not trigger any acknowledgement at all. But non-persistent messaging is more suitable for streaming data applications.

Relative function calls

Publish persistent message:

• ipushSendPSubjectData()
• ipushSendPQueueData()

Publish non-persistent message:

• ipushSendNPSubjectData()
• ipushSendNPQueueData()

!! Both Pub/Sub and P2P messaging models with subject addressing support persistent and non-persistent messaging.

By proceeding durable subscription, the receiver can make iPush Server saving the messages of subscribed subjects for him/her when the he/she goes off-line. iPush Server will keep these messages in disk storage while the durable subscriber is off-line, and send these saved messages immediately to the durable subscriber when he/she is back on-line.

Durable subscription is an important feature of guaranteed delivery (another one is persistent publishing).

On the contrary, non-durable (general) subscription won't make iPush Server saving any message when the subscriber is off-line.

Relative function calls

Durable subscription / unsubscription:

• ipushSubDSubject()
• ipushUnsubDSubject()

Non-durable subscription / unsubscription:

• ipushSubSubject()
• ipushUnsubSubject()

!! The durable subscription can only proceeded in subject addressing.

Although the TCP/IP protocol already provides some level of guaranteed delivery but it can't handle situations like crashed servers or saving messages for off-line users. The guaranteed delivery capability of iPush Server is designed to solve these problems.

The two most important features of guaranteed delivery are:

• persistent publishing
• durable subscription

There are some other features also implemented in iPush system to help achieving guaranteed delivery, like:

• once-and-only-once
• store-and-forward

!! The guaranteed delivery capability can only be brought by subject addressing.

In order to achieve higher efficiency in message receiving, iPush API will automatically divide a single large message into smaller packets for transmition. This operation can prevent an iPush client program from choking in receiving a single large message.

The default size of the divided packet is about 3 KB (3072 bytes, exactly). The valid value for subject packet size is from 1 to 7168. Developer can change the value by setting parameter in API.

A subject message can be assigned a message priority value by sender. The valid value for message priority is from 1 to 15, larger value means higher priority; default 1.

The message priority will be used on server side only when the sending buffer for receiver jammed, high priority messages will cut in the line to be pushed.

Relative function calls

Publish persistent/non-persistent message:

• ipushSendPSubjectData()
• ipushSendPQueueData()
• ipushSendNPSubjectData()
• ipushSendNPQueueData()

A subject message can be assigned a QoS value by sender. The valid value for QoS is from 0 to 3, larger value means better QoS; default 3.

The QoS will be used on server side only when the sending buffer for receiver jammed, the messages with the least QoS value will be dropped if the sending buffer full.

Relative function calls

Publish persistent/non-persistent message:

• ipushSendPSubjectData()
• ipushSendPQueueData()
• ipushSendNPSubjectData()
• ipushSendNPQueueData()

A persistent subject message can be assigned a TTL value by sender. TTL means the time period (in second) that iPush Server can store it. After the TTL expired, iPush Sever would not transmit it to any subscriber thereafter and it will be removed upon iPush Server performs MsgDB cleanup.

Default value of TTL is 0, means 1 day (86400 seconds).

Some APIs let developer assign the TTL value in separated day, hour, minute, and second parameters, some APIs in single one parameter (in second) only.

Relative function calls

Publish persistent message:

• ipushSendPSubjectData()
• ipushSendPQueueData()

Each client connection will be automatically assigned a connection ID (12-bit integer) by iPush Server. The connection ID of the message sender can be learned by receiver on subject message receiving event.

Please keep aware of iPush doesn't guarantee the unique and sequence between the assigned connection IDs though they are often different and increasing in general.

Relative function calls

Receiving subject message callback function:

• SetSubjectData() - in ActiveX Control APIs
• OnSetSubjectData() - in .NET Framework and .NET Compact Framework APIs
• onSubjectMessage() - in Java and Flash AS2 APIs
• onSubjectData() - in Linux C and Windows DLL APIs

Each message sent(published) to iPush Server will be automatically assigned a message ID (32-bit integer). The message ID can be learned by receiver on subject message receiving event.

Please keep aware of iPush doesn't guarantee the unique and sequence between the assigned message IDs though they are often different and increasing in general.

Relative function calls

Receiving subject message callback function:

• SetSubjectData() - in ActiveX Control APIs
• OnSetSubjectData() - in .NET Framework and .NET Compact Framework APIs
• onSubjectMessage() - in Java and Flash AS2 APIs
• onSubjectData() - in Linux C and Windows DLL APIs

This is an iPush related service for license control. A legal and valid license file (.lic, commercial or trial) from ICE Technology is required for the license daemon running normally. The official service name of license daemon is:

• ICE License Daemon V2 (in Windows)
• ipushld (in Linux)

Relative iPush services

• auth. center
• iPush kernel

This is an iPush related service for user authentication and authorization. We call it AC shortly. When an user proceeds to connect to iPush Server, AC will verify if the user account is valid. Upon the valid user proceeds the action for message sending or subscribing, AC will verify the write permission or read permission of the user account to allow or reject the respective action. The official service name of auth. center is:

• ICE Auth Center V2 (in Windows)
• ipushac (in Linux)

Relative iPush services

• license daemon
• iPush kernel

This is the kernel service of iPush for message handling and transportation. We call it iPush service sometimes. Several components of iPush kernel are in charge of channel addressing, subject addressing, Pub/Sub messaging, P2P messaging, etc.. The official service name of iPush kernel is:

• ICE iPush V2 (in Windows)
• ipushd (in Linux)

Relative iPush services

• license daemon
• auth. center

This is a web-based management system developed in JSP and servlet. It requests JDK, Tomcat, and MySQL for working. It provides the user interfaces for iPush administrator to monitor and manage iPush system.

Several iPush BackOffice CGIs (JSP files) are also provided for integrating with other system to access the iPush user database.

More on to Learn - iPush BackOffice