/*********************************************************************************************************
* Software License Agreement (BSD License)                                                               *
* Author: Sebastien Decugis <sdecugis@nict.go.jp>							 *
*													 *
* Copyright (c) 2008, WIDE Project and NICT								 *
* All rights reserved.											 *
* 													 *
* Redistribution and use of this software in source and binary forms, with or without modification, are  *
* permitted provided that the following conditions are met:						 *
* 													 *
* * Redistributions of source code must retain the above 						 *
*   copyright notice, this list of conditions and the 							 *
*   following disclaimer.										 *
*    													 *
* * Redistributions in binary form must reproduce the above 						 *
*   copyright notice, this list of conditions and the 							 *
*   following disclaimer in the documentation and/or other						 *
*   materials provided with the distribution.								 *
* 													 *
* * Neither the name of the WIDE Project or NICT nor the 						 *
*   names of its contributors may be used to endorse or 						 *
*   promote products derived from this software without 						 *
*   specific prior written permission of WIDE Project and 						 *
*   NICT.												 *
* 													 *
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED *
* WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A *
* PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR *
* ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 	 *
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 	 *
* INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR *
* TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF   *
* ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.								 *
*********************************************************************************************************/

/* Messages module.
 * 
 * This module allows to manipulate the msg_t and msg_avp_t structures that represents a Diameter message in memory.
 * See message-api.h for more information on the functions and types involved.
 *
 * When a Diameter message is received on an interface, the process is as follow:
 *   - The peer thread receives the message from the transport layer and saves it as a buffer.
 *   - The Security module handles this message and decrypt the content as needed, as a new buffer.
 *   - The function "msg_parse_buffer" is called to quickly check the structure and coherency of the message.
 *   - A first level of filters is applied from header information: Answer message without corresponding request, ...
 *   - The function "msg_parse_dict" is called to save all AVP values in the msg structure. The buffer is then discarded.
 *   - The message is queued for handling by the routing daemon.
 *   - When the message is picked, the function will decide on the destination of the message and modify it accordingly.
 *     - If the message is put for local delivery, "msg_parse_rules" will be called. Conflicting messages can not be handled.
 *     - If the message is put for forwarding, the forwarding callbacks functions are called (to set the route-record and/or proxy information).
 *       - then the message is put in the outgoing global queue.
 *       - the routing daemon pick the message, determines the next hop, and put the message in the peer's outgoing queue.
 *       - the peer picks the message, set the hop-by-hop id, and call "msg_bufferize". The buffer is passed to the security module (encrypt) then to the transport layer (send).
 *        - the msg object may be saved in the "sent" peer queue for failover and for matching the answer; or the object is freed.
 */
 
#ifndef _MESSAGE_H
#define _MESSAGE_H

/* Include the API for the messages */
#include <waaad/message-api.h>

 
/* The following functions are called only from the daemon */

/*
 * FUNCTION:	msg_init
 *
 * PARAMETERS:
 *  -
 *
 * DESCRIPTION: 
 *  Initialize the message module. 
 *
 * RETURN VALUE:
 *   0	: Application is now ready to use the module.
 *  !0  : An error occurred. 
 */
int msg_init ( void );

/*
 * FUNCTION:	msg_fini
 *
 * PARAMETERS:
 *  -
 *
 * DESCRIPTION: 
 *  Terminates the module. No msg_* function must be called after this one.
 *
 * RETURN VALUE:
 *   0 : module closed properly.
 *  !0 : an error occurred (we may ignore it)
 */
int msg_fini ( void );


/*
 * FUNCTION:	msg_parse_buffer
 *
 * PARAMETERS:
 *  buffer 	: Pointer to a buffer containing a message received from the network. 
 *  msg		: Upon success, this points to a valid msg_t object. No AVP value is resolved in this object, nor grouped AVP.
 *
 * DESCRIPTION: 
 *   This function parses a buffer an creates a msg_t object to represent the structure of the message.
 *  Since no dictionary lookup is performed, the values of the AVP are not interpreted. To achieve this,
 *  the returned message object must be passed to msg_parse_dict.
 *
 * RETURN VALUE:
 *  0      	: The location has been written.
 *  EINVAL 	: The buffer does not contain a valid Diameter message.
 *  ENOMEM	: Unable to allocate enough memory to create the msg_t object.
 */
int msg_parse_buffer ( char * buffer, msg_t ** msg );

/*
 * FUNCTION:	msg_bufferize
 *
 * PARAMETERS:
 *  msg		: A valid msg_t object. All AVP must have a value. 
 *  buffer 	: Upon success, this points to an allocated buffer of the message that can be passed to the security layer. 
 *		 The buffer may be freed after use.
 *  is_routable : Upon success, the information if the message is routable or not (contains Destination-Realm) is written here if not NULL. 
 *		 1: msg routable, 0: msg not routable
 *
 * DESCRIPTION: 
 *   This function parses a buffer an creates a msg_t object to represent the structure of the message.
 *  Since no dictionary lookup is performed, the values of the AVP are not interpreted. To achieve this,
 *  the returned message object must be passed to msg_parse_dict.
 *
 * RETURN VALUE:
 *  0      	: The location has been written.
 *  EINVAL 	: The buffer does not contain a valid Diameter message.
 *  ENOMEM	: Unable to allocate enough memory to create the msg_t object.
 */
int msg_bufferize ( msg_t * msg, char ** buffer, int * is_routable );

/*
 * FUNCTION:	msg_parse_dict
 *
 * PARAMETERS:
 *  msg		: A msg_t object as returned by msg_parse_buffer.
 *
 * DESCRIPTION: 
 *   This function looks for the command and each AVP definition in the dictionary.
 *  If the dictionary definition is found, avp_model is set and the value of the AVP is interpreted accordingly and:
 *   - for grouped AVPs, the children AVP are created and interpreted also.
 *   - for numerical AVPs, the value is converted to host byte order and saved to appropriate avp_data field.
 *   - for octetstring AVPs, the string is copied into a new buffer and its address is put in avp_data. 
 *  If the dictionary definition is not found, avp_model is left to NULL and
 *  the content of the AVP is saved as an octetstring in an internal structure. avp_data is NULL.
 *  As a result, after this function has been called, there is no more dependency of the msg object to the message buffer, that can be freed.
 *
 * RETURN VALUE:
 *  0      	: The message has been fully parsed as described.
 *  EINVAL 	: the msg parameter is invalid for this operation.
 *  ENOMEM	: Unable to allocate enough memory to complete the operation.
 */
int msg_parse_dict ( msg_t * msg );

/*
 * FUNCTION:	msg_dump
 *
 * PARAMETERS:
 *  obj		: A msg_t or msg_avp_t object.
 *
 * DESCRIPTION: 
 *   This function dumps the content of a message to the log facility (using log_debug)
 *
 * RETURN VALUE:
 *   -
 */
void msg_dump ( void * obj );




#endif /* _MESSAGE_H */