| /* $Id$ | |
| * | |
| * Licensed to the Apache Software Foundation (ASF) under one or more | |
| * contributor license agreements. See the NOTICE file distributed with | |
| * this work for additional information regarding copyright ownership. | |
| * The ASF licenses this file to you under the Apache License, Version | |
| * 2.0 (the "License"); you may not use this file except in compliance | |
| * with the License. You may obtain a copy of the License at | |
| * | |
| * http://www.apache.org/licenses/LICENSE-2.0 | |
| * | |
| * Unless required by applicable law or agreed to in writing, software | |
| * distributed under the License is distributed on an "AS IS" BASIS, | |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | |
| * See the License for the specific language governing permissions and | |
| * limitations under the License. | |
| */ | |
| /* | |
| * etch_mailboxint.h | |
| * mailbox interface | |
| */ | |
| #ifndef ETCHIMAILBOX_H | |
| #define ETCHIMAILBOX_H | |
| #include "etchobj.h" | |
| #include "etch_message.h" | |
| #define ETCH_MAILBOX_TIMEOUT (-2) | |
| #define ETCH_MAILBOX_DUPLICATE (-3) | |
| typedef struct i_mailbox i_mailbox; | |
| /** | |
| * etch_mailbox_notify() | |
| * notify interface callback to receive notification of mailbox status changes. | |
| * @remarks accomodation is made for a single status listener only. | |
| * @param thisx caller | |
| * @param mb the mailbox whose status has changed. | |
| * @param state the state object specified during callback registration. | |
| * @param closed true if the mailbox timeout has expired and the mailbox is now closed to delivery, | |
| * false if a message has arrived. | |
| */ | |
| typedef int (*etch_mailbox_notify) (void* thisx, i_mailbox* mb, void* state, const int is_closed); | |
| /** | |
| * etch_mailbox_element | |
| * this is for now an etch object, in case it needs to own the message | |
| */ | |
| typedef struct etch_mailbox_element | |
| { | |
| unsigned int hashkey; | |
| unsigned short obj_type; | |
| unsigned short class_id; | |
| struct objmask* vtab; | |
| int (*destroy)(void*); | |
| void*(*clone) (void*); | |
| obj_gethashkey get_hashkey; | |
| struct objmask* parent; | |
| etchresult* result; | |
| unsigned int refcount; | |
| unsigned int length; | |
| unsigned char is_null; | |
| unsigned char is_copy; | |
| unsigned char is_static; | |
| unsigned char reserved; | |
| etch_message* msg; | |
| etch_who* whofrom; | |
| } etch_mailbox_element; | |
| /* - - - - - - - - - - - - - - - - - | |
| * signatures of i_mailbox virtuals | |
| * - - - - - - - - - - - - - - - - - | |
| */ | |
| /** | |
| * etch_mailbox_message() | |
| * queues the specified message to this mailbox. | |
| * @param thisx caller | |
| * @param msg the message to be received, caller relinquishes on success, retains on failure. | |
| * @param whofrom sender, caller retains | |
| * @return 0 success, -1 failure. | |
| */ | |
| typedef int (*etch_mailbox_message)(void* thisx, void* whofrom, void* msg); | |
| /** | |
| * etch_mailbox_read() | |
| * reads the next message from the mailbox, waiting indefinitely for a message to be delivered. | |
| * @param thisx caller | |
| * @param out location to receive the etch_mailbox_element* result. | |
| * @return 0 success, -1 failure. on success, out location is populated with the requested message. | |
| * if mailbox is empty and closed, result will be zero and *out will contain null. | |
| * -1 this indicates an exception condition, not an empty condition. | |
| */ | |
| typedef int (*etch_mailbox_read) (void* thisx, etch_mailbox_element** out); | |
| /** | |
| * etch_mailbox_read_withwait() | |
| * reads the next message from the mailbox, waiting the specified time for a message to be delivered. | |
| * @param thisx caller | |
| * @param maxdelay the maximum amount of time in milliseconds to wait for a message when the | |
| * mailbox is empty. zero indicates wait indefinitely, -1 indicates do not wait. | |
| * @param out location to receive the etch_mailbox_element* result. | |
| * @return 0 success, -1 failure. on success, out location is populated with the requested message. | |
| * if mailbox is empty and closed, result will be zero and *out will contain null. | |
| * -1 this indicates an exception condition, not an empty condition. | |
| */ | |
| typedef int (*etch_mailbox_read_withwait) (void* thisx, const int maxdelay, etch_mailbox_element** out); | |
| /** | |
| * etch_mailbox_close_delivery() | |
| * closes the mailbox such that no more messages can be delivered to it. | |
| * any messages currently queued will continue to be processed. | |
| * @param thisx caller | |
| * @return 0 if mailbox was closed successfuly, -1 if mailbox was already closed or could not be closed. | |
| */ | |
| typedef int (*etch_mailbox_close_delivery) (void* thisx); | |
| /** | |
| * etch_mailbox_close_read() | |
| * closes the mailbox such that no more messages can be delivered to it or read from it. | |
| * any messages currently queued will be delivered to a default handler. | |
| * @param thisx caller | |
| * @return 0 if mailbox was closed successfuly, -1 if mailbox was already closed or could not be closed. | |
| */ | |
| typedef int (*etch_mailbox_close_read) (void* thisx); | |
| /** | |
| * etch_mailbox_register_notify() | |
| * register a etch_mailbox_notify callback to receive notification of mailbox status changes. | |
| * @param thisx caller | |
| * @param notify pointer to a function conforming to the etch_mailbox_notify signature. | |
| * @param state a value to pass through via the supplied notify callback. | |
| * @param maxdelay the maximum amount of time in milliseconds to wait for delivery of the notification. | |
| * zero indicates wait indefinitely, -1 indicates do not wait. | |
| * @return 0 on success, -1 if a callback is already registered, or on exception condition. | |
| */ | |
| typedef int (*etch_mailbox_register_notify) (void* thisx, etch_mailbox_notify, void* state, const int maxdelay); | |
| /** | |
| * etch_mailbox_unregister_notify() | |
| * remove the specified etch_mailbox_notify callback. cancels any current timeout. | |
| * @param thisx caller | |
| * @param notify pointer to a function conforming to the etch_mailbox_notify signature. | |
| * @return 0 if specified callback was unregistered or -1 is specified calback is not currently | |
| * registered, or on exception condition. | |
| */ | |
| typedef int (*etch_mailbox_unregister_notify) (void* thisx, etch_mailbox_notify); | |
| /** | |
| * etch_mailbox_is_empty() | |
| * @return boolean value indicating if specified mailbox is empty | |
| */ | |
| typedef int (*etch_mailbox_is_empty) (void* thisx); | |
| /** | |
| * etch_mailbox_is_closed() | |
| * @return boolean value indicating if specified mailbox is closed | |
| */ | |
| typedef int (*etch_mailbox_is_closed) (void* thisx); | |
| /** | |
| * etch_mailbox_is_full() | |
| * @return boolean value indicating if specified mailbox is full | |
| */ | |
| typedef int (*etch_mailbox_is_full) (void* thisx); | |
| /** @return the message id of this mailbox */ | |
| typedef int64 (*etch_mailbox_get_message_id) (void* thiz); | |
| /** @return the concrete etch_mailbox object for this mailbox */ | |
| typedef struct etch_plainmailbox etch_mailbox; | |
| typedef etch_mailbox* (*etch_mailbox_get_implobj) (void*); | |
| /** @return the manager for this mailbox */ | |
| typedef struct i_mailbox_manager i_mailbox_manager; | |
| typedef i_mailbox_manager* (*etch_mailbox_get_manager) (void*); | |
| /* - - - - - - - - - - - - - - - - - | |
| * i_mailbox | |
| * - - - - - - - - - - - - - - - - - | |
| */ | |
| /** | |
| * i_mailbox | |
| * mailbox interface | |
| */ | |
| typedef struct i_mailbox | |
| { | |
| unsigned int hashkey; | |
| unsigned short obj_type; | |
| unsigned short class_id; | |
| struct objmask* vtab; | |
| int (*destroy)(void*); | |
| void*(*clone) (void*); | |
| obj_gethashkey get_hashkey; | |
| struct objmask* parent; | |
| etchresult* result; | |
| unsigned int refcount; | |
| unsigned int length; | |
| unsigned char is_null; | |
| unsigned char is_copy; | |
| unsigned char is_static; | |
| unsigned char reserved; | |
| void* thisx; /* instantiating object */ | |
| etch_mailbox_get_implobj mailbox; | |
| etch_mailbox_get_manager manager; | |
| etch_mailbox_message message; | |
| etch_mailbox_read read; | |
| etch_mailbox_read_withwait read_withwait; | |
| etch_mailbox_close_delivery close_delivery; | |
| etch_mailbox_close_read close_read; | |
| etch_mailbox_register_notify register_notify; | |
| etch_mailbox_unregister_notify unregister_notify; | |
| etch_mailbox_is_empty is_empty; | |
| etch_mailbox_is_closed is_closed; | |
| etch_mailbox_is_full is_full; | |
| etch_mailbox_get_message_id get_message_id; | |
| } i_mailbox; | |
| /* - - - - - - - - - - - - - - - - - | |
| * public methods | |
| * - - - - - - - - - - - - - - - - - | |
| */ | |
| /** | |
| * new_mailbox_element() | |
| * etch_mailbox_element constructor | |
| * @param msg todo document ownership | |
| * @param whofrom todo document ownership | |
| */ | |
| etch_mailbox_element* new_mailbox_element(etch_message* msg, etch_who* whofrom); | |
| /** | |
| * new_default_mailbox_interface() | |
| * i_mailbox constructor | |
| * populates all virtuals with stub methods. | |
| * @param thisx instantiator object | |
| */ | |
| i_mailbox* new_default_mailbox_interface(void* thisx); | |
| /** | |
| * etch_mailbox_get_implobj() | |
| * verify and return the concrete mailbox implementation | |
| */ | |
| etch_mailbox* etchmbox_get_implobj(i_mailbox*); | |
| /** | |
| * etch_mailbox_get_manager() | |
| * verify and return the mailbox's mailbox manager | |
| */ | |
| i_mailbox_manager* etchmbox_get_manager(i_mailbox*); | |
| /** | |
| * new_mailbox_interface() | |
| * i_mailbox constructor | |
| * populates virtuals with specified methods. | |
| * @param thisx instantiator object. | |
| * @param balance of parameters are pointers to virtual method implementations. | |
| */ | |
| i_mailbox* new_mailbox_interface(void* thisx, | |
| etch_mailbox_message, | |
| etch_mailbox_read, | |
| etch_mailbox_read_withwait, | |
| etch_mailbox_close_delivery, | |
| etch_mailbox_close_read, | |
| etch_mailbox_register_notify, | |
| etch_mailbox_unregister_notify, | |
| etch_mailbox_is_empty, | |
| etch_mailbox_is_closed, | |
| etch_mailbox_is_full, | |
| etch_mailbox_get_message_id); | |
| #endif /* ETCHIMAILBOX_H */ |