/* $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 */