/* $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 "etch_object.h" #include "etch_message.h" #ifdef __cplusplus extern "C" { #endif #define ETCH_MAILBOX_TIMEOUT (-2) #define ETCH_MAILBOX_DUPLICATE (-3) struct i_mailbox; struct i_mailbox_manager; /** * 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, struct 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 etch_object* vtab; etch_object_destructor destroy; etch_object_clone clone; obj_gethashkey get_hashkey; struct etch_object* 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_mutex_hookproc synchook; etch_mutex_t* synclock; 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, etch_who* whofrom, etch_message* 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, etch_object* 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) (struct i_mailbox*); /** @return the manager for this mailbox */ typedef struct i_mailbox_manager* (*etch_mailbox_get_manager) (struct i_mailbox*); /* - - - - - - - - - - - - - - - - - * i_mailbox * - - - - - - - - - - - - - - - - - */ /** * i_mailbox * mailbox interface */ typedef struct i_mailbox { unsigned int hashkey; unsigned short obj_type; unsigned short class_id; struct etch_object* vtab; etch_object_destructor destroy; etch_object_clone clone; obj_gethashkey get_hashkey; struct etch_object* 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_mutex_hookproc synchook; etch_mutex_t* synclock; 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 */ struct 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); #ifdef __cplusplus } #endif #endif /* ETCHIMAILBOX_H */