interface.h

extremeDB s sample code,useful for you

/*******************************************************************
 *                                                                 *
 *  This file is a part of the eXtremeDB-HA Application Framework  *
 *  Copyright (c) 2001-2006 McObject LLC                           * 
 *  All Rights Reserved                                            *
 *                                                                 *
 *******************************************************************/
/**
 *\file       interface.h
 *
 *\brief      Definitions of interface & transport layers of HA
 * ++
 * 
 * PROJECT:   eXtremeDB(tm) (c) 2003 McObject LLC\n
 *
 * SUBSYSTEM: HA support framework\n
 *
 *
 *
 * VERSION:   1.0\n
 *
 * HISTORY:\n
 *                 1 SS     25-Jul-2003 Created it was\n
 *
 * --
 */

/*
 * This file contains definitions of HA interfase layer and transport layer of HA communication
 * protocols.
 * Interface layer is used by application.
 * Transport layer is used by communication protocols.
 * ( see the short description of HA communication protocol for the details in 
 *  /framework/framework.c )
 */
/*
  This sample demonstrates how master and replicas establish the connection and
  the data exchange:

      MASTER                               REPLICA

    (the connection functions are called explicitly by application)

    mco_nw_attach_replica(...);       
                                        mco_nw_attach_master(...);

    (send - receive functions are called implicitly by HA subsystem)
 .........................................................
    mco_nw_send(...);
                                        mco_nw_recv(...);
                                        mco_nw_send(...);
    mco_nw_recv(...);
 .........................................................

(called implicitly by the HA error     
 handler or explicitly by the application)
                            (called explicitly by application)

    mco_nw_close(...);                  mco_nw_close(...);
*/
 
#ifndef _APPNW_H_
  #define _APPNW_H_

#ifdef __cplusplus
  extern "C" { 
#endif

#include <platform.h>
#include <mcoHA.h>

/**
 *      Configuration of the communication channel:
 *
 *  Allow output of debug messages in communication protocol
 */ 
#define NW_DEBUG_OUTPUT

/**\def CFG_SHARED_COMMIT
 *
 *    The option CFG_SHARED_COMMIT enables HA with several processes sharing
 *  the same segment of shared memory in MULTIPROCESS_SHM mode.
 *
 *  The schema below explains how the shared commit works:
 *
 *                  -------------                 -------------
 *                  | master    |                 | replica   |
 *                  | process 3 |    ------------>| process 1 |
 *     ------------>| (passive) |    |            -------------
 *     |            -------------    |
 *     |                             |
 *     |            -------------    |            -------------
 *     |            | master    |    |            | replica   |
 *     | ---------->| process 2 |    |    ------->| process 2 |
 *     | |          | (passive) |    |    |       -------------
 *     | |          -------------    |    |
 *     V V                           |    |
 * -------------    -------------<---|    |       -------------
 * |   shared  |<-->| master    |<--------|       | replica   |
 * |   commmit |    | process 1 |<--------------->| process 3 |
 * |    thread |    | (active)  |                 -------------
 * -------------    -------------
 *  
 * If you wish to use HA with several master processes accessing the
 * shared memory database in your own implementation of the communication channel,
 * you should create a separate thread in the 'main' master process in order to implement
 * the "shared commit". This thread should call mco_HA_trans_commit_synch() function.
 * Note that the mco_HA_trans_commit_synch()  will return an error if the shared commit
 * has not been initialized yet. If the shared commit mode has been set the function enters
 * the internal loop and never return control back to the application
 * (see the thread SynchCommit() in modules appnw... .c)
 * You must set the shared commit mode via mco_HA_set_mode () function.
 * In order to set this mode set the par.is_master field to
 * MCO_MULTIPROCESS_COMMIT.
 *
 */ 
//#define CFG_SHARED_COMMIT

/*
 * Shared commit MUST NOT be defined under Windows CE
 */
#ifdef CFG_SHARED_COMMIT
  #ifdef _WIN32_WCE
    #error Shared commit is NOT supported under Windows CE !!!
  #endif
#endif

/**
 *   You need to choose among the following kinds of communication channel \n
 *	between MASTER and REPLICAs:
 *
 *      1) BSD TCP sockets;
 *      2) BSD UDP sockets;
 *      3) pipes;
 *      4) QNX messaging (only for QNX);
 *      5) user defined channel.
 */ 
#ifdef _DOC_  //section for documentation
/** 
  declare the "CFG_TCP_SOCKET_CHANNEL 1" definition 
  in order to use channel-over-TCP.
 */
#define CFG_TCP_SOCKET_CHANNEL    1
/**
  declare the "CFG_UDP_SOCKET_CHANNEL 1" definition 
  in order to use channel-over-UDP.
 */
#define CFG_UDP_SOCKET_CHANNEL    1
/**
    declare the "CFG_PIPE_CHANNEL	1" definition 
    in order to use channel-over-pipes.
 */
#define CFG_PIPE_CHANNEL          1
/**
    declare the "CFG_QNXMSG_CHANNEL 1" definition 
    in order to use channel-over-QNX-messaging.
 */
#define CFG_QNXMSG_CHANNEL        1
#endif

#define CFG_TCP_SOCKET_CHANNEL    1
//#define CFG_UDP_SOCKET_CHANNEL    1
//#define CFG_PIPE_CHANNEL          1
//#define CFG_QNXMSG_CHANNEL        1

    
/**\def CFG_USER_DEFINED_CHANNEL
 * User defined channel "CFG_USER_DEFINED_CHANNEL 1" is chosen by default
 * (if no other channel is defined).*/

#if	(!(CFG_TCP_SOCKET_CHANNEL|CFG_UDP_SOCKET_CHANNEL|CFG_PIPE_CHANNEL|CFG_QNXMSG_CHANNEL))
	#define CFG_USER_DEFINED_CHANNEL	1
#endif

/** **********************************************************************\n
   Descriptor of master/replica interconnection channel
   It's the extention of the channel descriptor defined in MCO.
   User MAY add the necessary fields here  depending on the channel type.
   The pointer to this structure is passed to the HA instead of the pointer to 
   the mco_channel_t structure.

  typedef struct nw_channel_
  {
   mco_channel_t   mco_channel;
    uint2           status;
    ...
  }nw_channel_t, *nw_channel_h;

  This descriptor is defined in headers for each type of the communication 
  channel independently in the headers below.
\n*************************************************************************/

/* these headers MUST be included after the certain communication 
    channel is chozen */
#include  "hatcp.h"
#include  "haudp.h"
#include  "hapipes.h"
#include  "haQMSG.h"

enum StatusFlags  {
  NWST_CANCEL      = 0x800,   /**< cancel flag */
  NWST_IS_MASTER   = 0x1000,  /**< The channel belongs to master */
  NWST_CONNECTED   = 0x2000,  /**< The channel is connected */
  NWST_LISTEN      = 0x4000,  /**< The status of the channel is "listening" */
  NWST_INITIALIZED = 0x8000,  /**< The channel is initialized */
};

/** **********************************************************************\n
 *          Possible error codes                                           * 
 ***************************************************************************/

#define MCO_ERR_NW        MCO_E_HAFRAMEWORK /**< BASE error code */

#define MCO_E_NW_FATAL    MCO_ERR_NW + 0  /**< fatal error                      */
#define MCO_E_NW_NOTSUPP  MCO_ERR_NW + 1  /**< network is not supported         */
#define MCO_E_NW_ERROR    MCO_ERR_NW + 2  /**< other errors                     */

#define MCO_E_NW_BUSY     MCO_ERR_NW + 3  /**< network busy (another listener?) */
#define MCO_E_NW_ACCEPT   MCO_ERR_NW + 4  /**< accept failed                    */
#define MCO_E_NW_TIMEOUT  MCO_ERR_NW + 5  /**< timeout exceeded                 */
#define MCO_E_NW_INVADDR  MCO_ERR_NW + 6  /**< invalid address specified        */
#define MCO_E_NW_NOMEM    MCO_ERR_NW + 7  /**< host name is too long            */
#define MCO_E_NW_CONNECT  MCO_ERR_NW + 8  /**< connect failed                   */
#define MCO_E_NW_SENDERR  MCO_ERR_NW + 9  /**< receive failed                   */
#define MCO_E_NW_RECVERR  MCO_ERR_NW + 10 /**< receive just failed              */
#define MCO_E_NW_CLOSED   MCO_ERR_NW + 11 /**< connection was closed (by the remote host) */  
#define MCO_E_NW_CANCEL   MCO_ERR_NW + 12 /**< connection was canceled */  
/** master is killed by replica */
#define MCO_E_NW_KILLED_BY_REPLICA  MCO_E_KILLED_BY_REPLICA

/** *************************************************************\n
 *\struct _HA_ interface.h "/include/interface.h"                \n 
 *   Sample HA interface class.                                  \n 
 * It includes the handle of database instance                   \n 
 * For each database instance that is using HA must be created   \n 
 * the corresponding HA object                                   \n 
 *****************************************************************/

typedef struct _HA_ {
  nw_channel_t  baseChan;                    /**< base HA interface channel */
  int2          replicaMode;                 /**< the copy of global flag "replica_mode" */
  int2          isMainMaster;                /**< the copy of global flag "main_master" */
  int2          id;                          /**< ID of HA instance */
  void	        * start_mem;                 /**< pointer to database memory */
  char          dbName[NW_MAX_NAMELENGTH];   /**< database name */
  char          endpoint[NW_MAX_NAMELENGTH]; /**< master's endpoint for the remote connections */
  THREAD_ID     hConnThread;                 /**< ListenToReplicas() thread handle */
  THREAD_ID     hSynchcommit;                /**< SynchCommit() thread handle  */
  THREAD_ID     hAsyncWr;                    /**< AsyncWrite() thread handle */
  THREAD_ID     hWorking;                    /**< master - replica working thread handle */
#ifndef __cplusplus                          
  mco_db_h      db;                          /**< database handle */
  mco_trans_h	t;                           /**< transaction descriptor pointer 
                                                  for "C" only. in C++ implementation these
                                                  members are inherited from parent class */
#endif
}ha_t, * ha_h;
  
/** **********************************************************************\n
 *                                                                        \n
 *          Definitions of the communication protocol functions           \n 
 *                                                                        \n
 * Interface layer. Used by master - replica interconnections.            \n 
 * The interface is simplified. All the internal protocol details are     \n
 * hidden behind this layer from the application and MCOdb HA             \n 
 *                                                                        \n
 *************************************************************************\n
 *
 * \fn MCO_RET mco_nw_attach_replica(                 
 *	      mco_db_h db, 	const char* devname,
 *             const mco_connection_param_t * params,
 *            	const char* replica_name,
 *             timer_unit timeout,
 *             void * arg);
 *
 * Description:\n
 * This function includes connection algotrithm dependent on the type of a communication
 * channel. It attaches connected replica to HA subsystem.
 *
 *\param IN	mco_db_h db       - database descriptor pointer.
 *\param IN	const char*       - devname. MUST be no more than NW_MAX_NAMELENGTH.
 *\param IN const mco_connection_param_t* params - connection & transaction timeouts.
 *\param IN	const char* replica_name - replica name (optional).
 *\param IN unsigned long timeout    - wait-for-connection timeout
 *\param IN OUT void * arg    - user defined argument. In C++ applications it may be 
 *\param implemented as pointer to the instance of user defined class.
 *\param In C application it may be implemented in any way.