plug_export.h

/*
  nazwa="Plug Export"
  info="Nagłówek wymagany w każdej wtyczce (załącza plug.h)."
*/
/**
\file
Nagłówek eksportujący deklaracje funkcji wymagane przez rdzeń do poprawnej komunikacji.
Od razu importuje plug_shared.h.
Dodatkowo kilka funkcji / makr dla Waszej wygody :)
*/

#ifndef PLUGEXPORTH
#define PLUGEXPORTH

#include "plug.h"
#pragma pack(push, 1)

extern cCtrl * Ctrl;

#ifndef KONNEKT_SDK_NOEXPORT
 /**< Wskaznik do struktury #cCtrl.
                    Przy jej pomocy możliwy jest dostęp do funkcji rdzenia.
                    */
/*
Funkcje eksportowane
*/
/**
  Deklaracja jedynej eksportowanej z wtyczki funkcji.
*/
extern "C"
   __declspec(dllexport) int __stdcall IMessageProc(sIMessage_base * msgBase);
#endif

/*
  Wszystkie nastepne funkcje sa funkcjami TYLKO pomocniczymi ... Mozna je usunac , ale
najwygodniej jest z nich po prostu korzystac :)
*/


  /**
  \brief Jeżeli program działa w trybie Debug loguje treść wiadomości do pliku konnekt.log (i do okna).
  \param format Format dokładnie taki sam jak przy funkcjach printf
  \param parametry Parametry potrzebne do utworzenia wiadomości

  Funkcja wysyła do rdzenia #IMessage #IMC_LOG (która nic nie robi, ale jej treść może zostać zalogowana
  w trybie Debug).
  \attention W trybie \i Debug dostępne jest okno debugowania (IMLOG) w którym pokazywana jest treść IMLOG!
  */
  void IMLOG(const char *format, ...);

  /** Wysyła IMLOG z komunikatem ostatniego błędu systemu Windows (GetLastError())
  */
  void IMERROR();


  /** Wysyła wiadomość . Wywołuje bezpośrednio cCtrl::IMessage .
  \param id Identyfikator wiadomości
  \param net Docelowa sieć wtyczek
  \param type Docelowy typ wtyczek
  \param p1,p2 Parametry
  \sa gr_im net_ imt_
  */
  inline int IMessage(unsigned int  id , signed int net=0 , unsigned int type=-1 , int p1=0 , int p2=0);
  /** Wysyła wiadomość . Wywołuje bezpośrednio cCtrl::IMessage .
  */
  inline int IMessage(sIMessage_base * msg);


  /** Wysyła wiadomość bezpośrednio do rdzenia/ui (net = 0 , type = 0) .
  \param id Identyfikator wiadomości
  \param p1,p2 Parametry
  \sa im_
  */
  inline int ICMessage(unsigned int  id , int p1=0 , int p2=0);

  /** Wysyła wiadomość bezpośrednio do wtyczki.
  \param id Identyfikator wiadomości
  \param plug ID wtyczki
  \param p1,p2 Parametry
  \sa im_ imc_plug_
  */
  inline int IMessageDirect(unsigned int  id , unsigned int plug=0, int p1=0 , int p2=0);

  /** Wysyła wiadomość bezpośrednio do wtyczki.*/
  inline int IMessageDirect(unsigned int plug , sIMessage_base * msg);


  void WMProcess(void);

// ****************** THREAD SAFE

  /// \defgroup ThreadSafe Makra do przełączania wątków.
  /// \{


  /** Przełączanie wiadomości do prawidłowych wątków.
  Jeżeli wiadomość zawiera kod , który \b MUSI być wykonany
  w głównym wątku (np. tworzenie okien) można na początku
  kodu akcji wstawić #THREADSAFE. <br>
  Sposób działania (wątek "prawidłowy" to wątek w którym powinna działać wiadomość) :
    - Makro sprawdza ID aktualnego wątku
      - Jeżeli jest równe ID \i prawidłowego wątku wykonuje dalej...
      - Jeżeli jest różne , kolejkuje procedurę APC w \i prawidłowym
        wątku i oczekuje na zwrócenie wartości.
  <br><br>
  Przykład:
  \code
   int __stdcall IMessageProc(sIMessage_base * msg) {
     switch (msg->id) {
        case IM_NIEZABEZPIECZANA:
           return 1;
        case IM_ZABEZPIECZANA:
           IMESSAGE_TS();
           // Potencjalnie niebezpieczne operacje...
           return 1;
     }
     if (Ctrl) Ctrl->setError(IMERROR_NORESULT);
                                  // Jeżeli wiadomość nie zwraca konkretnego wyniku
                                  // MUSI to zaznaczyć!
     return 0;
   }
  \endcode
  \attention Użycie makra jest dozwolone tylko jeżeli nie został
  jeszcze wykonany \b żaden fragment kodu należący do wiadomości. (powinien
  być wstawiony \b od \b razu po \b case IM_...: .
  \attention "Przełączanie" odbywa się poprzez procedury APC (patrz: MSDN)
  Aby nie powiesić całego programu wszystkie zdarzenia oczekujące
  (Sleep , Wait itp.) muszą być wykonywane w trybie Alertable
  (SleepEx , Wait...Ex itp.) , tak żeby procedura APC mogła być wykonana ...
  \attention Jeżeli zdaje ci się że wieszasz kolejki APC głównego wątku
  włącz Test w oknie @Dev...
  */
  #define IMESSAGE_TS() \
    if (Ctrl->Is_TUS(0)) return Ctrl->RecallTS()
  /**
  To samo co #IMESSAGE_TS tyle, że bez oczekiwania na wynik.
  \warning Opcja potencjalnie niebezpieczna. Może być używana tylko przy prostych
    wiadomościach, najlepiej nie przechowujących w swoich parametrach \b żadnych
    wskaźników (w momencie gdy wiadomość zostanie przetworzona, wskaźniki mogą już
    prowadzić do zwolnionych obszarów pamięci).
  */
  #define IMESSAGE_TS_NOWAIT(ret) \
    if (Ctrl->Is_TUS(0)) {Ctrl->RecallTS(0,0);return ret;}


  /// \}

  /**@defgroup gr_cfg Korzystanie z tablic ustawień.
     @{*/
     const char * SAFECHAR(const char * ch);  ///< Sprawdza czy \a ch nie jest == 0. Jeśli jest - zwraca pusty ciąg znaków.
                                                             /// \param ch (char *)
     /**Zwraca wartość tekstową z tablicy kontaktów.
     \param row (int) ID kontaktu
     \param id  (int) ID kolumny
     \param buff Bufor do którego ma zostać zapisana wartość. 
     \param size Rozmiar bufora.
     \return (const char *)
     Jeżeli jako \a buff i \a size podamy 0, otrzymamy wskaźnik do kopii wartości
     przechowywanej w buforze tymczasowym (cCtrl::GetTempBuff). Jeżeli wcześniej
     zablokujemy tablicę, otrzymamy najprawdopodobniej wskaźnik bezpośredni.
     Jeżeli \a buff będzie równy 0, a \a size -1, otrzymamy kopię wartości
     w świeżo zaalokowanej strukturze, którą należy zwolnić przez cCtrl::free.
     \sa #GETCNTCA
     */
     const char * GETCNTC(int row , int id , char * buff = 0 , unsigned int size = 0);
     /**Zwraca wartość tekstową (w nowym buforze) z tablicy kontaktów.
     \param row (int) ID kontaktu
     \param id  (int) ID kolumny
     \return (const char *)
     \attention Zwrócony bufor trzeba zwolnić przy pomocy cCtrl::free !
     */
     #define GETCNTCA(row , id) GETCNTC(row , id , 0 , -1)


     /**Zwraca wartość liczbową (4 bajty) z tablicy kontaktów.
     \param row (int) ID kontaktu
     \param id  (int) ID kolumny
     \return (int)*/
     int GETCNTI(int row , int id);

	 __int64 GETCNTI64(int row , int id);


     /**Ustawia wartość tekstową w tablicy kontaktów.
     \param row (int) ID kontaktu
     \param id  (int) ID kolumny
     \param val (char*) wartość do ustawienia
     */
     bool SETCNTC(int row , int id , const char * val);
     /**Ustawia wartość liczbową (4 bajty) w tablicy kontaktów.
     \param row (int) ID kontaktu
     \param id  (int) ID kolumny
     \param val (int) wartość do ustawienia
     \param mask (int) maska ustawianych bitów
     */
     bool SETCNTI(int row , int id , int val, int mask=-1);
     bool SETCNTI64(int row , int id , __int64 val, __int64 mask=-1);
     /**Ustawia wartość liczbową (4 bajty) z użyciem maski w tablicy kontaktów.
     \param row (int) ID kontaktu
     \param id  (int) ID kolumny
     \param val (char*) wartość do ustawienia
     \param mask (int) Maska, wskazująca które bity mają być zmodyfikowane.
     */

     /**Sprawdza czy \a row jest identyfikatorem, czy numerem wiersza.
     \param row (int) wartość do sprawdzenia
     \return (bool) true/false
     */
     #define ISCNTID(row) (((row)!=0xFFFFFFFF)&&((row)&DT_ROWID_MASK)) // Sprawdza czy row jest identyfikatorem

     /**Zwraca identyfikator kontaktu.
     \param row (int) Numer wiersza z kontaktem w tablicy (ale może być też identyfikator)
     \return (int) identyfikator kontaktu.
     */
     #define GETCNTID(row) (ISCNTID(row)?row:Ctrl->DTgetID(DTCNT , (row)))
     /**Zwraca wiersz w tablicy z kontaktem.
     \param row (int) Identyfikator kontaktu (ale może być też numer wiersza)
     \return (int) Numer wiersza kontaktu.
     */
     #define GETCNTPOS(row) (ISCNTID(row)?Ctrl->DTgetPos(DTCNT , (row)):row)

#ifndef _DTABLE_
    #define DT_ISROWID(row) (((row)!=0xFFFFFFFF)&&((row)&DT_ROWID_MASK)) // Sprawdza czy row jest identyfikatorem
    #define DT_MASKID(row) ((row)|DT_ROWID_MASK)
    #define DT_UNMASKID(row) (row&(~DT_ROWID_MASK)) // Zdejumuje maske z identyfikatora
#endif

     /**Zwraca wartość liczbową (4 bajty) z tablicy ustawień.
     \param id  (int) ID kolumny
     \return (int)*/
     int GETINT(int id);
     
     /**Zwraca wartość tekstową z tablicy ustawień.
     \param id  (int) ID kolumny
     \param buff Bufor do którego ma zostać zapisana wartość. 
     \param size Rozmiar bufora.
     \return (const char *)
     Jeżeli jako \a buff i \a size podamy 0, otrzymamy wskaźnik do kopii wartości
     przechowywanej w buforze tymczasowym (cCtrl::GetTempBuff). Jeżeli wcześniej
     zablokujemy tablicę, otrzymamy najprawdopodobniej wskaźnik bezpośredni.
     Jeżeli \a buff będzie równy 0, a \a size -1, otrzymamy kopię wartości
     w świeżo zaalokowanej strukturze, którą należy zwolnić przez cCtrl::free.
     \sa #GETSTRA
     */
     const char * GETSTR(int id , char * buff = 0 , unsigned int size = 0);
     #define GETSTRA(id) GETSTR(id , 0 , -1)
     /**Ustawia wartość liczbową (4 bajty) w tablicy ustawień.
     \param id  (int) ID kolumny
     \param val (int) wartość
     \param mask (int) maska ustawianych bitów
     */
     bool SETINT(int id , int val , int mask = -1);
     /**Ustawia wartość tekstową (char*) w tablicy ustawień.
     \param id  (int) ID kolumny
     \param val (char*) wartość
     */
     bool SETSTR(int id , const char * val);

     #ifdef _STRING_
       #define GETCNTS(row , id) (string(GETCNTC(row,id)))
       #define GETSTRING(id)       (string(GETSTR(id)))
     #endif


/** @} */


// *******************************************

  /** Ta funkcja powinna być użyta w #IM_INIT .
  Parametrami są \a p1 i \a p2 przesłane razem z #IM_INIT
  */
  int Plug_Init(int p1 , int p2);

  /** Ta funkcja powinna być użyta w #IM_DEINIT .
  Parametrami są \a p1 i \a p2 przesłane razem z #IM_DEINIT
  */
  void Plug_Deinit(int p1 , int p2);

// ********************************************
#ifdef __BORLANDC__
#define VSNPRINTF vsnprintf
#else
#define VSNPRINTF _vsnprintf
#endif
#ifdef IMLOG_AUTOALLOC
    char * __vsaprintf(const char *format, va_list ap);
#endif
/** @sa cCtrl::IMLOG() */
void IMLOG(const char *format, ...);
/** @sa cCtrl::IMDEBUG() */
void IMDEBUG(enDebugLevel level , const char *format, ...);

#ifdef _WINDOWS_
 void IMERROR();
#endif


#pragma pack(pop)


#endif