include/saMsg.h

   1 /*
   2  * Copyright (c) 2005 MontaVista Software, Inc.
   3  *
   4  * All rights reserved.
   5  *
   6  * Author: Steven Dake (sdake@mvista.com)
   7  *
   8  * This software licensed under BSD license, the text of which follows:
   9  *
  10  * Redistribution and use in source and binary forms, with or without
  11  * modification, are permitted provided that the following conditions are met:
  12  *
  13  * - Redistributions of source code must retain the above copyright notice,
  14  *   this list of conditions and the following disclaimer.
  15  * - Redistributions in binary form must reproduce the above copyright notice,
  16  *   this list of conditions and the following disclaimer in the documentation
  17  *   and/or other materials provided with the distribution.
  18  * - Neither the name of the MontaVista Software, Inc. nor the names of its
  19  *   contributors may be used to endorse or promote products derived from this
  20  *   software without specific prior written permission.
  21  *
  22  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
  23  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  24  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  25  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
  26  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  27  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  28  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  29  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  30  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  31  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
  32  * THE POSSIBILITY OF SUCH DAMAGE.
  33  */
  34
  35 #ifndef SAMSG_H_DEFINED
  36 #define SAMSG_H_DEFINED
  37
  38 #ifdef __cplusplus
  39 extern "C" {
  40 #endif
  41
  42 typedef SaUint64T SaMsgHandleT;
  43
  44 typedef SaUint64T SaMsgQueueHandleT;
  45
  46 typedef SaUint64T SaMsgSenderIdT;
  47
  48 #define SA_MSG_MESSAGE_DELIVERED_ACK 0x1
  49
  50 typedef SaUint32T SaMsgAckFlagsT;
  51
  52 #define SA_MSG_QUEUE_PERSISTENT 0x1
  53
  54 typedef SaUint32T SaMsgQueueCreationFlagsT;
  55
  56 #define SA_MSG_MESSAGE_HIGHEST_PRIORITY 0
  57 #define SA_MSG_MESSAGE_LOWEST_PRIORITY 3
  58
  59 typedef struct {
  60         SaMsgQueueCreationFlagsT creationFlags;
  61         SaSizeT size[SA_MSG_MESSAGE_LOWEST_PRIORITY + 1];
  62         SaTimeT retentionTime;
  63 } SaMsgQueueCreationAttributesT;
  64
  65 typedef enum {
  66         SA_MSG_QUEUE_GROUP_ROUND_ROBIN = 1,
  67         SA_MSG_QUEUE_GROUP_LOCAL_ROUND_ROBIN = 2,
  68         SA_MSG_QUEUE_GROUP_LOCAL_BEST_QUEUE = 3,
  69         SA_MSG_QUEUE_GROUP_BROADCAST = 4
  70 } SaMsgQueueGroupPolicyT;
  71
  72 #define SA_MSG_QUEUE_CREATE 0x1
  73 #define SA_MSG_QUEUE_RECEIVE_CALLBACK 0x2
  74 #define SA_MSG_QUEUE_EMPTY 0x4
  75
  76 typedef SaUint32T SaMsgQueueOpenFlagsT;
  77
  78 typedef struct {
  79         SaSizeT queueSize;
  80         SaSizeT queueUsed;
  81         SaUint32T numberOfMessages;
  82 } SaMsgQueueUsageT;
  83
  84 typedef struct {
  85         SaMsgQueueCreationFlagsT creationFlags;
  86         SaTimeT retentionTime;
  87         SaTimeT closeTime;
  88         SaMsgQueueUsageT saMsgQueueUsage[SA_MSG_MESSAGE_LOWEST_PRIORITY + 1];
  89 } SaMsgQueueStatusT;
  90
  91 typedef enum {
  92         SA_MSG_QUEUE_GROUP_NO_CHANGE = 1,
  93         SA_MSG_QUEUE_GROUP_ADDED = 2,
  94         SA_MSG_QUEUE_GROUP_REMOVED = 3,
  95         SA_MSG_QUEUE_GROUP_STATE_CHANGED = 4
  96 } SaMsgQueueGroupChangesT;
  97
  98 typedef struct {
  99         SaNameT queueName;
 100 } SaMsgQueueGroupMemberT;
 101
 102 typedef struct {
 103         SaMsgQueueGroupMemberT member;
 104         SaMsgQueueGroupChangesT change;
 105 } SaMsgQueueGroupNotificationT;
 106
 107 typedef struct {
 108         SaUint32T numberOfItems;
 109         SaMsgQueueGroupNotificationT *notification;
 110         SaMsgQueueGroupPolicyT queueGroupPolicy;
 111 } SaMsgQueueGroupNotificationBufferT;
 112
 113 typedef struct {
 114         SaUint32T type;
 115         SaUint32T version;
 116         SaSizeT size;
 117         SaNameT *senderName;
 118         void *data;
 119         SaUint8T priority;
 120 } SaMsgMessageT;
 121
 122 typedef void (*SaMsgQueueOpenCallbackT) (
 123         SaInvocationT invocation,
 124         SaMsgQueueHandleT queueHandle,
 125         SaAisErrorT error);
 126
 127 typedef void (*SaMsgQueueGroupTrackCallbackT) (
 128         const SaNameT *queueGroupName,
 129         const SaMsgQueueGroupNotificationBufferT *notificationBuffer,
 130         SaUint32T numberOfMembers,
 131         SaAisErrorT error);
 132
 133 typedef void (*SaMsgMessageDeliveredCallbackT) (
 134         SaInvocationT invocation,
 135         SaAisErrorT error);
 136
 137 typedef void (*SaMsgMessageReceivedCallbackT) (
 138         SaMsgQueueHandleT queueHandle);
 139
 140 typedef struct {
 141         SaMsgQueueOpenCallbackT saMsgQueueOpenCallback;
 142         SaMsgQueueGroupTrackCallbackT saMsgQueueGroupTrackCallback;
 143         SaMsgMessageDeliveredCallbackT saMsgMessageDeliveredCallback;
 144         SaMsgMessageReceivedCallbackT saMsgMessageReceivedCallback;
 145 } SaMsgCallbacksT;
 146
 147 SaAisErrorT
 148 saMsgInitialize (
 149         SaMsgHandleT *msgHandle,
 150         const SaMsgCallbacksT *msgCallbacks,
 151         SaVersionT *version);
 152
 153 SaAisErrorT saMsgSelectionObjectGet (
 154         SaMsgHandleT msgHandle,
 155         SaSelectionObjectT *selectionObject);
 156
 157 SaAisErrorT
 158 saMsgDispatch (
 159         SaMsgHandleT msgHandle,
 160         SaDispatchFlagsT dispatchFlags);
 161
 162 SaAisErrorT
 163 saMsgFinalize (
 164         SaMsgHandleT msgHandle);
 165
 166 SaAisErrorT
 167 saMsgQueueOpen (
 168         SaMsgHandleT msgHandle,
 169         const SaNameT *queueName,
 170         const SaMsgQueueCreationAttributesT *creationAttributes,
 171         SaMsgQueueOpenFlagsT openFlags,
 172         SaTimeT timeout,
 173         SaMsgQueueHandleT *queueHandle);
 174
 175 SaAisErrorT
 176 saMsgQueueOpenAsync (
 177         SaMsgHandleT msgHandle,
 178         SaInvocationT invocation,
 179         const SaNameT *queueName,
 180         const SaMsgQueueCreationAttributesT *creationAttributes,
 181         SaMsgQueueOpenFlagsT openFlags);
 182
 183 SaAisErrorT
 184 saMsgQueueClose (
 185         SaMsgQueueHandleT msgHandle);
 186
 187 SaAisErrorT
 188 saMsgQueueStatusGet (
 189         SaMsgQueueHandleT msgHandle,
 190         const SaNameT *queueName,
 191         SaMsgQueueStatusT *queueStatus);
 192
 193 SaAisErrorT
 194 saMsgQueueUnlink (
 195         SaMsgQueueHandleT msgHandle,
 196         const SaNameT *queueName);
 197
 198 SaAisErrorT
 199 saMsgQueueGroupCreate (
 200         SaMsgHandleT msgHandle,
 201         const SaNameT *queueGroupName,
 202         SaMsgQueueGroupPolicyT queueGroupPolicy);
 203
 204 SaAisErrorT
 205 saMsgQueueGroupInsert (
 206         SaMsgHandleT msgHandle,
 207         const SaNameT *queueGroupName,
 208         const SaNameT *queueName);
 209
 210 SaAisErrorT
 211 saMsgQueueGroupRemove (
 212         SaMsgHandleT msgHandle,
 213         const SaNameT *queueGroupName,
 214         const SaNameT *queueName);
 215
 216 SaAisErrorT
 217 saMsgQueueGroupDelete (
 218         SaMsgHandleT msgHandle,
 219         const SaNameT *queueGroupName);
 220
 221 SaAisErrorT
 222 saMsgQueueGroupTrack (
 223         SaMsgHandleT msgHandle,
 224         const SaNameT *queueGroupName,
 225         SaUint8T trackFlags,
 226         SaMsgQueueGroupNotificationBufferT *notificationBuffer);
 227
 228 SaAisErrorT
 229 saMsgQueueGroupTrackStop (
 230         SaMsgHandleT msgHandle,
 231         const SaNameT *queueGroupName);
 232
 233 SaAisErrorT
 234 saMsgMessageSend (
 235         SaMsgHandleT msgHandle,
 236         const SaNameT *destination,
 237         const SaMsgMessageT *message,
 238         SaTimeT timeout);
 239
 240 SaAisErrorT
 241 saMsgMessageSendAsync (
 242         SaMsgHandleT msgHandle,
 243         SaInvocationT invocation,
 244         const SaNameT *destination,
 245         const SaMsgMessageT *message,
 246         SaMsgAckFlagsT ackFlags);
 247
 248 SaAisErrorT
 249 saMsgMessageGet (
 250         SaMsgQueueHandleT queueHandle,
 251         SaMsgMessageT *message,
 252         SaTimeT *sendTIme,
 253         SaMsgSenderIdT *senderId,
 254         SaTimeT timeout);
 255
 256 SaAisErrorT
 257 saMsgMessageCancel (
 258         SaMsgQueueHandleT queueHandle);
 259
 260 SaAisErrorT
 261 saMsgMessageSendReceive (
 262         SaMsgHandleT msgHandle,
 263         const SaNameT *destination,
 264         const SaMsgMessageT *sendMessage,
 265         SaMsgMessageT *receiveMessage,
 266         SaTimeT *replySendTime,
 267         SaTimeT timeout);
 268
 269 SaAisErrorT
 270 saMsgMessageReply (
 271         SaMsgHandleT msgHandle,
 272         const SaMsgMessageT *replyMessage,
 273         const SaMsgSenderIdT *senderId,
 274         SaTimeT timeout);
 275
 276 SaAisErrorT saMsgMessageReplyAsync (
 277         SaMsgHandleT msgHandle,
 278         SaInvocationT invocation,
 279         const SaMsgMessageT *replyMessage,
 280         const SaMsgSenderIdT *senderId,
 281         SaMsgAckFlagsT ackFlags);
 282
 283 #endif /* SAMSG_H_DEFINED */
 284