1 mike  1.1 /*
  2           **==============================================================================
  3           **
  4           ** Open Management Infrastructure (OMI)
  5           **
  6           ** Copyright (c) Microsoft Corporation
  7           ** 
  8           ** Licensed under the Apache License, Version 2.0 (the "License"); you may not 
  9           ** use this file except in compliance with the License. You may obtain a copy 
 10           ** of the License at 
 11           **
 12           **     http://www.apache.org/licenses/LICENSE-2.0 
 13           **
 14           ** THIS CODE IS PROVIDED *AS IS* BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 15           ** KIND, EITHER EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION ANY IMPLIED 
 16           ** WARRANTIES OR CONDITIONS OF TITLE, FITNESS FOR A PARTICULAR PURPOSE, 
 17           ** MERCHANTABLITY OR NON-INFRINGEMENT. 
 18           **
 19           ** See the Apache 2 License for the specific language governing permissions 
 20           ** and limitations under the License.
 21           **
 22 mike  1.1 **==============================================================================
 23           */
 24           
 25           #ifndef _omi_protocol_h
 26           #define _omi_protocol_h
 27           
 28           #include "config.h"
 29           #include <string.h>
 30           #include <common.h>
 31           #include <base/messages.h>

 32 mike  1.2 #include <sock/selector.h>

 33 mike  1.1 
 34           BEGIN_EXTERNC
 35           
 36           typedef struct _Protocol Protocol;
 37           
 38           /*
 39               Callback for processing new message.
 40               Parameters:
 41               protocol - pointer to a protocol object that received a message
 42               message - message; consumer ahs to call 'AddRef' to keep message around
 43                   longer than callback's lifetime
 44               data - user-provided callback data
 45               Return:
 46                   normally callbacks should return TRUE (means keep connection open);
 47                   returning FALSE means close connection
 48           */
 49           typedef MI_Boolean (*ProtocolCallback)(
 50               Protocol* protocol,
 51               Message* message,
 52               void* data);
 53           
 54 mike  1.1 typedef enum _ProtocolEvent
 55           {
 56               PROTOCOLEVENT_CONNECT,
 57               PROTOCOLEVENT_CONNECT_FAILED,
 58               PROTOCOLEVENT_DISCONNECT
 59           }
 60           ProtocolEvent;
 61           
 62           typedef void (*ProtocolEventCallback)(
 63               Protocol* protocol,
 64               ProtocolEvent event,
 65               void* data);
 66           
 67           MI_Result Protocol_New_Listener(
 68               Protocol** self,
 69               Selector* selector, /*optional, maybe NULL*/
 70               const char* locator,
 71               ProtocolCallback callback,
 72               void* callbackData);
 73           
 74           /*
 75 mike  1.1     Creates new protocol object (client side) and
 76               connect it to the server.
 77           
 78               Parameters:
 79               self - [out] protocol object
 80               selector - [opt] selector to use for socket monitoring
 81               locator - server's address (typically domain socket file name)
 82               callback - function that protocol calls to inform about new messsages
 83               callbackData - 
 84               eventCallback - function that protocl calls to inform about socket states
 85                   connected/disconnected
 86               user, password [opt] - credentials for explicit auth. If NULL,
 87                   implicit authentication is used
 88           
 89               Returns:
 90               'OK' if succefful, error otherwise
 91           */
 92           MI_Result Protocol_New_Connector(
 93               Protocol** self,
 94               Selector* selector, /*optional, maybe NULL*/
 95               const char* locator,
 96 mike  1.1     ProtocolCallback callback,
 97               void* callbackData,
 98               ProtocolEventCallback eventCallback,
 99               void* eventCallbackData,
100               const char* user,
101               const char* password);
102           
103           /*
104               Creates a new protocol object from connected stream socket
105               (typically a pipe from server to agent).
106           
107               Parameters:
108               self - [out] protocol object
109               selector - [opt] selector to use for socket monitoring
110               s - socket; if protocol created successfully, socket will be closed in Protocol_Delete.
111                   If operation failed, socket is not closed.
112               skipInstanceUnpack - flag to skip instance un-packing; used 
113                   to skip unpacking instances from agent
114               callback - function that protocol calls to inform about new messsages
115               callbackData - 
116               eventCallback - function that protocl calls to inform about socket states
117 mike  1.1         connected/disconnected
118           
119               Returns:
120               'OK' if succefful, error otherwise
121           */
122           MI_Result Protocol_New_From_Socket(
123               Protocol** self,
124               Selector* selector, /*optional, maybe NULL*/
125               Sock s,
126               MI_Boolean skipInstanceUnpack,
127               ProtocolCallback callback,
128               void* callbackData,
129               ProtocolEventCallback eventCallback,
130               void* eventCallbackData);
131           
132           MI_Result Protocol_Delete(
133               Protocol* self);
134           
135           MI_Result Protocol_Run(
136               Protocol* self,
137               MI_Uint64 timeoutUsec);
138 mike  1.1 
139           MI_Result Protocol_Send(
140               Protocol* self,
141               Message* message);
142           
143           END_EXTERNC
144           
145           #endif /* _omi_protocol_h */