core_ctrl.h

#pragma once

#include "core_unique.h"
#include "core_plugin.h"
#include "core_tables.h"



/**Klasa służąca do komunikowania się z "rdzeniem" systemu wtyczek.

Adres tej struktury (zaalokowanej w rdzeniu) przekazywany jest
jako parametr w pierwszej wiadomosci do wtyczki - #IM_INIT ...<br>
Każda wtyczka posiada własną kopię cCtrl.
\sa IMessageProc()
*/
class cCtrl {
public:
	virtual int __stdcall getLevel()=0;  ///< Zwraca "poziom" dostepu do rdzenia. W 99% przypadków zwróci 1 ...
	virtual unsigned int __stdcall ID()=0;  ///< Zwraca identyfikator wtyczki.
	virtual HINSTANCE __stdcall hInst()=0;   ///<  Zwraca uchwyt procesu (HINSTANCE).
	virtual HINSTANCE __stdcall hDll()=0;   ///<  Zwraca uchwyt biblioteki wtyczki.

	virtual int __stdcall getError()=0; ///< Zwraca kod ostatniego błędu.
	virtual void __stdcall setError(int err_code)=0; ///< Ustawia kod błędu.
	///  Powinien byc ustawiony gdy wystapil blad przy ODBIORZE wiadomosci (np wiadomosc jest nieobslugiwana).
	///  \sa ImessageProc() imerror_
	virtual bool __stdcall isRunning()=0; ///< Zwraca 0 jeśli program jest w trakcie zamykania.
	///  Żadne dłuższe operacje nie powinny być wykonywane. Część IMessages
	///  w innych modułach i tak nie zostanie wykonana...
	/**
	Wysyła wiadomość do wtyczek.
	Aby przesłać wiadomość do rdzenia lub ui jako \i net i \i type trzeba podać 0
	\param msg Wiadomość do przesłania
	\sa im_ net_ imt_
	*/
	virtual int __stdcall IMessage(sIMessage_base * msg) = 0;
	/**  Wysyła wiadomość bezpośrednio do określonej wtyczki.
	\param msg Wiadomość do przesłania
	\param plug ID wtyczki
	\sa im_ imc_plug_
	*/
	virtual int __stdcall IMessageDirect(unsigned int plug , sIMessage_base * msg)=0;
	/** Zamienia (lub nie) identyfikator wiersza na jego numer.
	*/
	virtual int __stdcall DTgetPos(tTable db , unsigned int row)=0;
	/** Zamienia (lub nie) numer wiersza na jego identyfikator.
	*/
	virtual int __stdcall DTgetID(tTable db , unsigned int row)=0;
	virtual int __stdcall DTgetOld(tTable db , unsigned int row , unsigned int col)=0;
	virtual int __stdcall DTsetOld(tTable db , unsigned int row , unsigned int col , int val , int mask=0)=0;
	/** Pobieta typ kolumny \a id.
	\param id Identyfikator kolumny
	\return typ kolumny
	\sa \ref cfg dt_ct_
	*/
	virtual int __stdcall DTgetType(tTable db , unsigned int id)=0;
	/** Pobieta ilość wierszy w tablicy.
	\param db Identyfikator tablicy
	\sa \ref cfg dt_ct_
	*/
	virtual int __stdcall DTgetCount(tTable db)=0;
	/** Pobieta identyfikator kolumny o podanej nazwie.
	\param db Identyfikator tablicy
	\param name nazwa kolumny
	\sa \ref cfg dt_ct_
	*/
	virtual int __stdcall DTgetNameID(tTable db , const char * name)=0;

	virtual unsigned int __stdcall Is_TUS(unsigned int thID)=0; ///< Zwraca \a thID jeśli aktualny wątek jest różny od \a thID. Lub 0 gdy są równe. Jako \a thID można podać 0 - zostanie zamienione na główny wątek aplikacji.
	virtual int __stdcall RecallTS(HANDLE th = 0 , bool wait = 1)=0;
	virtual int __stdcall RecallIMTS(HANDLE th , bool wait , sIMessage_base * msg , int plugID)=0;

	virtual void __stdcall WMProcess()=0; ///< Opróżnienie kolejki wiadomości windowsowych.
	///  Powinno być wykonywane TYLKO w głównym wątku, w długich
	///  blokujących pętlach (aby odświeżyć wygląd okien)
	virtual void * __stdcall GetTempBuffer(unsigned int size)=0; ///< Zwraca wskaźnik do bufora tymczasowego o rozmiarze \a size.
	/// Bufor alokowany jest w kontekście wtyczki i wątku.
	/// \attention Nie można zwalniać tej pamięci!

	/** Pobiera wartosc wiersza z tablicy danych z konwersją typów.
	Konwersja odbywa się gdy Tables::Value::type jest różny od DT_CT_UNKNOWN. W
	przeciwnym wypadku jako typ przyjmowany jest typ kolumny.
	\param db Identyfikator tabeli
	\param row Identyfikator/numer wiersza
	\param col Identyfikator kolumny
	\param value Struktura z wartością
	\return wartość (lub adres do wartości jeśli typ != DT_CT_INT)
	\attention W #DTMSG można zapisywać tylko w określonych okolicznościach!
	*/
	virtual bool __stdcall DTget(tTable db , unsigned int row , unsigned int col , Tables::Value * value)=0;
	/** Ustawia wartosc wiersza z tablicy danych z konwersją typów.
	Konwersja odbywa się gdy Tables::Value::type jest różny od DT_CT_UNKNOWN. W
	przeciwnym wypadku jako typ przyjmowany jest typ kolumny.
	\param db Identyfikator tabeli
	\param row Identyfikator/numer wiersza
	\param col Identyfikator kolumny
	\param value Struktura do której zostanie zapisana wartość.
	\attention Do odczytu danych z #DTMSG przygotowane są inne funkcje!
	*/
	virtual bool __stdcall DTset(tTable db , unsigned int row , unsigned int col , Tables::Value * value)=0;
	/** Blokuje dostęp do wiersza w tablicy dla innych wątków. Zaraz po
	wykorzystaniu zabezpieczonych danych trzeba wywołać cCtrl::DTunlock z tymi
	samymi parametrami!
	\param db Identyfikator tabeli
	\param row Identyfikator/numer wiersza, lub -1 jeśli chcemy zablokować CAŁĄ tablicę
	\param reserved Zarezerwowane na później, musi być równe 0.
	\return Ilość wcześniej założonych blokad.
	*/
	virtual unsigned short __stdcall DTlock(tTable db , unsigned int row , int reserved=0)=0;
	/** Odblokowuje dostęp do wiersza w tablicy dla innych wątków,
	zastrzeżony wcześniej przy użyciu cCtrk::DTlock.
	\param db Identyfikator tabeli
	\param row Identyfikator/numer wiersza, lub -1 jeśli chcemy zablokować CAŁĄ tablicę
	\param reserved Zarezerwowane na później, musi być równe 0.
	\return Ilość pozostałych blokad.
	\attention Po wykonaniu tej funkcji, wszystkie zwrócone wskaźniki
	bezpośrednie mogą być już nieaktualne!
	*/
	virtual unsigned short __stdcall DTunlock(tTable db , unsigned int row , int reserved=0)=0;
	/** Wszystkie bufory wrzucane do API, żeby mogłby być zwolnione
	w innym module muszą być zaalokowane poniższą funkcją. */
	virtual void * __stdcall malloc(size_t size)=0; 
	/** Wszystkie bufory tekstowe wrzucane do API, żeby mogłby być zwolnione
	w innym module muszą być zaalokowane poniższą funkcją. */
	virtual char * __stdcall strdup(const char * str)=0;
	/** Wszystkie bufory zaalokowane przez cCtrl::malloc i cCtrl::strdup
	powinny być zwolnione tą funkcją. */
	virtual void __stdcall free(void * buff)=0;

	/** Używanie zwykłego Sleep w głównym wątku najprędzej doprowadzi
	K do stanu chwilowej nieużywalności, bardzo możliwe również,
	że nastąpi zupełny DeadLock.
	Zamiast tego można używać tej funkcji, która po prostu zamiast Sleep
	wywołuje MsgWaitForMultipleObjectsEx. Nie jest więc gwarantowane, 
	że podany czas w ogóle minie. Trzeba pamiętać też, że nie jest gwarantowane,
	że aktualny wątek nie wykona gdzieś po drodze innego kodu w wyniku
	wywołania f-cji APC, timer'a czy windowsowej wiadomości...
	Podczas zamykania (w IM_END) nie powinny być wywoływane procedury APC ani
	przełączanie wątków...
	Generalnie, jeżeli musisz czekać na coś w głównym wątku, używaj
	MsgWaitForMultipleObjectsEx w połączeniu z Ctrl->WMProcess, które
	przegląda kolejkę oczekujących wiadomości w aktualnym wątku.
	*/
	virtual int __stdcall Sleep(unsigned int time)=0;

	typedef unsigned int ( __stdcall * fBeginThread)( void * );

	/**
	BeginThread działa identycznie jak _beginthreadex z wyjątkiem
	tego, że w trybie debug potrafi wychwytywać błędy w wątku
	i je raportować... Używanie wysoko zalecane!
	@warn Funkcja zwraca uchwyt wątku! Należy go zamknąć przy pomocy CloseHandle()!!!
	*/
	virtual HANDLE __stdcall BeginThreadOld(void *security,
		unsigned stack_size,
		fBeginThread start_address,
		void *arglist=0,
		unsigned initflag=0,
		unsigned *thrdaddr=0
		)=0;
	/** Tworzy wątek i czeka aż się skończy.
	Parametry te same co w cCtrl::BeginThread()
	*/
	int BeginThreadAndWait(const char * name, void *security,	unsigned stack_size, fBeginThread start_address, void *arglist=0, unsigned initflag=0, unsigned *thrdaddr=0);

	/** Pobiera poziom debugowania dla wtyczki */
	virtual unsigned int __stdcall DebugLevel(enDebugLevel level = DBG_ALL)=0;

	/** Podaje, czy Konnekt jest zamykany w trybie natychmiastowym (np. podczas zamykania systemu).
	Wtyczki nie powinny w tym czasie wykonywać długich operacji, przełączać wątków (#IMESSAGE_TS),
	ani przetwarzać procedur APC (flaga Alertable w funkcjach oczekujących WinApi).
	*/
	virtual bool __stdcall QuickShutdown()=0;

	/** Ustawia poziom debugowania wtyczki.
	*/
	virtual unsigned int __stdcall SetDebugLevel(enDebugLevel levelMask, enDebugLevel level = DBG_ALL)=0;

	/** Pobiera nazwe kolumny o podanym identyfikatorze.
	\param db Identyfikator tablicy
	\param col Identyfikator kolumny
	\sa \ref cfg dt_ct_
	*/
	virtual const char * __stdcall DTgetName(tTable db , unsigned int col)=0;

	virtual Unique::tId __stdcall getId(Unique::tDomainId domainId, const char * name) = 0;
	virtual const char * __stdcall getName(Unique::tDomainId domainId, Unique::tId id) = 0;
	Unique::tDomainId getDomainId(const char * name) {return (Unique::tDomainId) this->getId(Unique::domainDomain, name);}
	Unique::tRangeId getRangeId(const char * name) {return (Unique::tRangeId) this->getId(Unique::domainRange, name);}
	virtual bool __stdcall idInRange(Unique::tDomainId domainId, Unique::tRangeId rangeId, Unique::tId id) = 0;
	virtual Unique::tRangeId __stdcall idInRange(Unique::tDomainId domainId, Unique::tId id, Unique::Range::enType check = Unique::Range::typeBoth) = 0;

	virtual Tables::oTable __stdcall DT(Tables::tTableId tableId)=0;
	/** Zwraca obiekt wtyczki.
	@param pluginId identyfikator, indeks, lub pluginNotFound jeżeli chcemy uzyskać obiekt przypisany do cCtrl.
	*/
	virtual Konnekt::oPlugin __stdcall getPlugin(Konnekt::tPluginId pluginId = pluginNotFound)=0;

	virtual HANDLE __stdcall BeginThread(const char* name, void *security,
		unsigned stack_size,
		fBeginThread start_address,
		void *arglist=0,
		unsigned initflag=0,
		unsigned *thrdaddr=0
		)=0;

	/** Nadaje nazwę wykonywanemu wątkowi, inicjalizuje bufory tymczasowe i dodaje do listy kontrolowanych wątków (które zostaną np. zatrzymane w chwili wystąpienia błędu krytycznego).
	@warning Musi być wywołane Z poziomu wątku!
	@notice Funkcja ta wywoływana jest automatycznie zaraz po utworzeniu wątku.
	*/
	virtual void __stdcall onThreadStart(const char* name=0) = 0;
	/** Zwalnia bufory tymczasowe i usuwa z listy kontrolowanych wątków.
	@warning Musi być wywołane Z poziomu wątku!
	@notice Funkcja ta wywoływana jest automatycznie zaraz przed zakończeniem wątku.
	*/
	virtual void __stdcall onThreadEnd()=0;


	// funkcje lokalne, dla ulatwienia
	int DTgetInt(tTable db , unsigned int row , unsigned int col);
	bool DTsetInt(tTable db , unsigned int row , unsigned int col , int value , int mask = -1);
	char * DTgetStr(tTable db , unsigned int row , unsigned int col , char * buff = 0 , unsigned int size = 0);
	bool DTsetStr(tTable db , unsigned int row , unsigned int col , const char * value);
	__int64 DTgetInt64(tTable db , unsigned int row , unsigned int col);
	bool DTsetInt64(tTable db , unsigned int row , unsigned int col , __int64 value , __int64 mask = -1);

	int DTgetInt(tTable db , unsigned int row , const char * name);
	bool DTsetInt(tTable db , unsigned int row , const char * name , int value , int mask = -1);
	char * DTgetStr(tTable db , unsigned int row , const char * name , char * buff = 0 , unsigned int size = 0);
	bool DTsetStr(tTable db , unsigned int row , const char * name , const char * value);
	__int64 DTgetInt64(tTable db , unsigned int row , const char * name);
	bool DTsetInt64(tTable db , unsigned int row , const char * name , __int64 value , __int64 mask = -1);


	/** Zapisuje sfromatowaną informację do pliku konnekt.log (i ew. wyświetla ją w oknie @Dev) */
	void IMLOG(const char *format, ...);
	/** Loguje, jeżeli wtyczka ma włączone logowanie na danym "poziomie" */
	void IMDEBUG(enDebugLevel level , const char *format, ...);
	void IMLOG_(enDebugLevel level , const char *format, va_list p);

	// ----
	inline int IMessage(unsigned int  id , signed int net=0 , unsigned int type=-1 , int p1=0 , int p2=0);
	inline int ICMessage(unsigned int  id , int p1=0 , int p2=0);
	inline int IMessageDirect(unsigned int  id , unsigned int plug=0, int p1=0 , int p2=0);

	int UIActionInsert(int _parent , int _id , int _pos , int _status=0 , const char * _txt = 0 , int _p1=0 , short _w=0 , short _h=0 , int _p2=0 , int _param=0);

	inline int SetColumn(tTable table , int id , int type , int def , const char * name);
	inline int SetColumn(tTable table , int id , int type , const char * def  , const char * name=0) {
		return this->SetColumn(table , id , type , (int)def , name);
	}

	inline operator oPlugin () {
		return this->getPlugin();
	}

};




/*  #define DTCFG  0x0  ///< Tablica konfiguracji.
#define DTCNT  0x1  ///< Tablica kontaktów.
#define DTMSG  0x2  ///< Tablica wiadomości.
#define DTNONE -1*/