// DamExchange

// DamExchange protocol versie 1, DLL implementatie versie 1.15

// dxpccall.h -- API interface voor DXP.DLL versie 1.15 (Windows 98/Me/2000/XP)
// Laatste update: 07-Jan-2004
// Copyright (c) 1997-2004  F.G.A. Mesander


//
// Gebruik deze include file DXPCCALL.H in de C sources die onderstaande functies aanroepen
// Link het damprogramma aan DXP.LIB
// Op deze wijze gebruikt het programma de functies uit DXP.DLL
// Deze include file behoeft (dient) niet aangepast te worden
// DXP.DLL en MSVCRT.DLL moeten in dezelfde directory als de EXE file staan, of in \WINDOWS\SYSTEM


//
// Ontwikkeld en getest met Microsoft Visual C++ 6.0, Service Pack 5
//



#ifdef __cplusplus
extern "C" {
#endif

#ifdef DXP_DLL_COMPILE
  #define DXPAPI __declspec(dllexport)
#else
  #define DXPAPI __declspec(dllimport)
#endif


// DXP.DLL implementeert 6 functies waarmee damprogramma's via DamExchange kunnen communiceren

// Functies voor het maken van een verbinding
//    dxp_oldremote_connect        (oud REMOTE protocol, niet gebruiken voor nieuwe implementaties)
//    dxp_socket_connect           (maak verbinding voor laag 1 SOCKET protocol)
//    dxp_nulmodem_connect         (maak verbinding voor laag 1 NULMODEM protocol)

// Functie voor het verbreken van een verbinding
//    dxp_disconnect               (verbreek de verbinding ongeacht het laag 1 protocol)

// Functies voor het verzenden en ontvangen van een DamExchange bericht
// Het verzenden en ontvangen vindt asynchroon plaats
//    dxp_send_message             (zend een DamExchange bericht ongeacht de soort verbinding)
//    dxp_receive_message          (ontvang een DamExchange bericht ongeacht de soort verbinding)


// Voordat een DamExchange bericht verzonden of ontvangen kan worden moet eerst een verbinding
// gemaakt worden met een van de 'connect' functies. De 'connect' functies moeten zolang zij
// de return waarde -1 teruggeven herhaald (in een loop) aangeroepen worden. Dit is o.a.
// bedoeld om in het damprogramma een Cancel dialoog box te kunnen implementeren.
// Een return waarde kleiner dan -1 geeft aan dat er een fout is opgetreden.
// De return code is 0 indien de verbinding succesvol tot stand gebracht is.

// Bij de 'connect' functies moet als eerste parameter een connection id meegegeven worden. De connection
// id geeft aan welke 'logische' verbinding opgezet moet worden. Connection id kan 0, 1 of 2 zijn
// omdat deze DLL ondersteuning biedt voor 3 gelijktijdige DamExchange verbindingen.
// Het is de taak van het aanroepende damprogramma om dxp_disconnect() aan te roepen met
// dezelfde connection id als waarmee de verbinding tot stand gebracht is.

// Bij de 'connect' functies wordt in twee parameters meegegeven welke user notify-message (parameter
// dxpusrmsg) naar welk window (parameter hwnd) gestuurd moet worden bij ontvangst van een
// DamExchange bericht of bij het wegvallen van de verbinding.
// Op deze manier hoeft het damprogramma niet in een loop te testen of een nieuw
// DamExchange bericht ontvangen is. Bij ontvangst van de notify-message in het damprogramma
// bevat wParam het type DamExchange bericht (DXP_GAMEREQ..DXP_CONNECTIONLOST) en lParam de
// connection id.




// Connect via commpoort, voor oude REMOTE interface, niet meer gebruiken voor nieuwe programma's
// Parameters:
//    connection_id   nummer van de logische verbinding, 0, 1 of 2
//    commport        nummer van de comm poort op de PC
//    hwnd            handle van het window dat de notify-messages moet ontvangen
//    dxpusrmsg       notify-message, normaal gesproken WM_USER + n
DXPAPI int dxp_oldremote_connect(int connection_id, int commport, HWND hwnd, UINT dxpusrmsg);

// Connect of listen via TCP/IP, voor DamExchange/SOCKET protocol
// Parameters:
//    connection_id   nummer van de logische verbinding, 0, 1 of 2
//    ip              ip adres waarnaar geconnect moet worden, bijvoorbeeld "192.140.78.6";
//                    gebruik "127.0.0.1" als geconnect moet worden naar een damprogramma
//            op dezelfde computer;
//                    door als parameter 0, NULL of een lege string te geven, wordt gewacht op
//                    een connect door het andere damprogramma (listen functie)
//    hwnd            handle van het window dat de notify-messages moet ontvangen
//    dxpusrmsg       notify-message, normaal gesproken WM_USER + n
DXPAPI int dxp_socket_connect(int connection_id, char *ip, HWND hwnd, UINT dxpusrmsg);   

// Connect via commpoort, voor DamExchange/NULMODEM protocol
// Parameters:
//    connection_id   nummer van de logische verbinding, 0, 1 of 2
//    commport        nummer van de comm poort op de PC
//    hwnd            handle van het window dat de notify-messages moet ontvangen
//    dxpusrmsg       notify-message, normaal gesproken WM_USER + n
DXPAPI int dxp_nulmodem_connect(int connection_id, int commport, HWND hwnd, UINT dxpusrmsg);



// Functie voor het verbreken van de verbinding met connection_id
// Het maakt niet uit met welke van de drie 'connect' functies de verbinding tot stand was gebracht als
// maar wel dezelfde connection id wordt gebruikt.
// Parameters:
//    connection_id   nummer van de logische verbinding, 0, 1 of 2
DXPAPI void dxp_disconnect(int connection_id);



// Bij ontvangst van de notify-message in het damprogramma bevat wParam het type DamExchange
// bericht (DXP_GAMEREQ..DXP_CONNECTIONLOST) en lParam de connection id.
// Op ontvangst van de notify-message moet in het damprogramma met de functie dxp_receive_message()
// de inhoud van het DamExchange bericht geplaatst worden in een variabele van type DXP_MESSAGE.
// Dit geldt niet als wParam bij de notify-message DXP_CONNECTIONLOST is. In dat geval is de verbinding
// met de connection id (in lParam) verbroken.


// Define's om het DamExchange bericht-type te identificeren.
// Tevens de waarde van wParam bij de user notify-message
#define DXP_GAMEREQ         1
#define DXP_GAMEACC         2
#define DXP_MOVE         3
#define DXP_GAMEEND         4
#define DXP_CHAT         5
#define DXP_BACKREQ         6
#define DXP_BACKACC         7
#define   DXP_OLDREMOTE         99
#define   DXP_CONNECTIONLOST    100   // geen DamExchange bericht-type

// Maximale lengte van de naam van een damprogramma (exclusief terminating '\0').
#define MAX_DXP_PROGRAMMA_NAAM_LEN  32

// Maximale lengte van een CHAT regel (exclusief terminating '\0').
#define MAX_DXP_CHAT_REGEL_LEN  126


#pragma pack(1)

typedef
struct tagDXP_MESSAGE
  {
  int dxp_message_type;  // DXP_GAMEREQ .. DXP_BACKACC, DXP_OLDREMOTE
  union
    {
    struct // DXP_GAMEREQ
      {
      short int   versie;          // versie van DamExchange, huidige versie is 1
      char   naam_initiator[MAX_DXP_PROGRAMMA_NAAM_LEN + 1];   // ASCIIZ string
      char   kleur_volger;       // 'W' of 'Z' voor wit resp. zwart
      short int   denktijd;       // in minuten voor de hele partij
      short int   aantal_zetten;       // voor de hele partij
      char   kleur_aan_zet;       // 'W' of 'Z' voor wit resp. zwart
      char   beginstand[50];       // 'e', 'w', 'z', 'W', 'Z'
      } dxp_gamereq;

    struct // DXP_GAMEACC
      {
      char   naam_volger[MAX_DXP_PROGRAMMA_NAAM_LEN + 1];   // ASCIIZ string
      short int   acceptatie_code;  // 0, 1, 2 of 3
      } dxp_gameacc;

    struct // DXP_MOVE
      {
      short int   tijd;           // in seconden
      short int begin_veld;        // 1..50
      short int eind_veld;        // 1..50
      short int   aantal_geslagen;     // 0..20
      short int   geslagen_stukken[20];     // elk 1..50
      } dxp_move;

    struct // DXP_GAMEEND
      {
      short int reden;          // 0, 1 of 2
      short int   stop_code;       // 0 of 1
      } dxp_gameend;

    struct // DXP_CHAT
      {
      char   chat_regel[MAX_DXP_CHAT_REGEL_LEN + 1];
      } dxp_chat;

    struct // DXP_BACKREQ
      {
      short int zet_nummer;       // 1..999
      char   kleur_aan_zet;       // 'W' of 'Z' voor wit resp. zwart
      } dxp_backreq;

    struct // DXP_BACKACC
      {
      short int   acceptatie_code;    // 0, 1 of 2
      } dxp_backacc;

    struct // DXP_OLDREMOTE
      {
      short int begin_veld;        // 1..50
      short int eind_veld;        // 1..50
      short int   aantal_geslagen;     // 0..20
      short int   geslagen_stukken[20];     // elk 1..50
      } dxp_oldremote;

    };
  } DXP_MESSAGE;

#pragma pack()



// Bij ontvangst van de notify message moet de volgende functie aangeroepen worden.
// Test echter eerst op de waarde van wParam op gelijkheid met DXP_CONNECTIONLOST, in dat
// geval moet deze functie niet aangeroepen worden.
// Als de functie wordt aangeroepen terwijl er geen DamExchange bericht binnengekomen is,
// is p_dxp_message->dxp_message_type na aanroep van de functie gelijk aan 0.
// De functie mag aangeroepen worden met als tweede parameter NULL om het binnengekomen
// DamExchange bericht op te halen maar verder te negeren.
// Deze functie returnt onmiddellijk, ongeacht of wel of geen DamExchange bericht binnen is.
// Parameters:
//    connection_id   nummer van de logische verbinding (0, 1 of 2), dus aanroepen met de
//            waarde van lParam bij ontvangst van de notify message
//    p_dxp_message   de struct is na aanroep van de functie gevuld met de complete
//                    informatie van het ontvangen DamExchange bericht of met
//            p_dxp_message->dxp_message_type gelijk aan 0
//                    de struct hoeft niet geinitialiseerd te worden voor aanroep van de functie
DXPAPI void dxp_receive_message(int connection_id, DXP_MESSAGE *p_dxp_message);



// Het verzenden van een DamExchange bericht.
// Deze functie returnt onmiddellijk, het DamExchange bericht wordt asynchroon verzonden.
// Parameters:
//    connection_id   nummer van de logische verbinding, 0, 1 of 2
//    p_dxp_message   de struct moet voor aanroep van de functie gevuld worden met de complete
//                    informatie van een DamExchange bericht, de inhoud van de struct wordt
//                    door deze aanroep niet gewijzigd
DXPAPI void dxp_send_message(int connection_id, DXP_MESSAGE *p_dxp_message);


#ifdef __cplusplus
}
#endif