Poradniki - Podstawowa wtyczka

Nauczymy się jak za pomocą klasy kAPI::Wtyczka::Wtyczka napisać podstawową wtyczkę

Co powinieneś napierw przeczytać

• Co pobrać i gdzie zapisać
• Utworzenie nowego projektu dla wtyczki
• Dodanie biblioteki kPI do projektu

Pisanie wtyczki dla konnekta przy użyciu powyższej klasy jest dziecinnie proste. Utwórzmy sobie najpierw klasę reprezentującą naszą nową wtyczkę. Plik ten nazwijmy nazwą naszej wtyczki czyli "mojaWtyczka.h"

#ifndef KONNEKT_MOJAWTYCZKA_H           // 1
#define KONNEKT_MOJAWTYCZKA_H

#include "wtyczka.h"                    // 2

using kAPI::Wtyczka;                    // 3

class MojaWtyczka : public Wtyczka      // 4
{

};

#endif //KONNEKT_MOJAWTYCZKA_H

Kodu tyle napisaliśmy co nic. Kilka wyjaśnień do poszczególnych lini kodu:

• 1 - klauzula #ifndef - #define - #endif zabezpiecza ten plik przed kilkukrotnym dołączeniem (poprzez wywołanie w różnych plikach instrukcji #include "mojaWtyczka.h") co spowodowało by błąd kompilacji. Niektórzy w tym celu używają instrukcji #pragma once, lecz metoda podana przezemnie jest powszechnie zalecana.
• 2 - dołączamy plik nagłówkowy z biblioteki kAPI z deklaracją klasy Wtyczka
• 3 - dzięki tej instrukcji mamy bezpośredni dostęp do klasy Wtyczka zawartej w przestrzeni kAPI. Gdybyśmy tego nie zrobili byśmy musieli wszędzie w kodzie zamiast używać zwyklej nazwy klasy Wtyczka, wymagane by było użycie kAPI::Wtyczka. Daje to nam również bezpośredni dostęp do kilku innych elementów biblioteki.
• 4 - klasa naszej własnej wtyczki dziedziczy po klasie Wtyczka z biblioteki kAPI

Utwórzmy jeszcze plik "main.cpp". Będzie to plik startowy naszej biblioteki

#include "mojaWtyczka.h"

int __stdcall DllMain(void * hinstDLL, unsigned long fdwReason, void * lpvReserved)
{
        return true;
}

int __stdcall IMessageProc( sIMessage_base * msgBase )
{
       switch (msgBase->id)                                                             // 1
       {
           case IM_PLUG_INIT: return Wtyczka::Init( new MojaWtyczka(), msgBase );       // 2
       }

       return Wtyczka::IMessageProc( msgBase );                                         // 3
}

W pliku tym znajdują się dwie główne funkcje. Funkcja DllMain jest standardową (wymaganą) funkcją każdej biblioteki dll. Jest więcj i w naszym projekcie. Natomiast funkcja IMessageProc jest funkcją wymaganą przez Konnekta dla każdej biblioteki będącej wtyczką. To przez nią rdzeń Konnekta komunikuję się z wtyczką wysyłąjąc jej powiadomienia. Poniżej objaśnię co się w niej dzieje.

• 1 - W tym bloku switch będziemy sprawdzać kody powiadomien jakie wysyłą do nas rdzeń. Sprawdzamy tylko te które nas interesują i na które chcemy odpowiedzieć.
• 2 - Powiadomienie IM_PLUG_INIT, musimy obsłużyć. Inaczej wtyczka nie zostanie załadowana. Najłatwiej obsłużyć to powiadomienie w pokazany sposób, czyli wywołać metodę Init z klasy Wtyczka. Jako parametry przyjmuje ona obiekt naszej wtyczki oraz wiadomość.
• 3 - Resztę powiadomień które wysyłą do nas wtyczka a my ich nie obsłużyliśmy przekazujemy do metody Wtyczka::IMessageProc

Jeśli teraz spróbujemy skompilować projekt dostaniemy kilka komunikatów błędów o treści: "prosta_wtyka error LNK2001: unresolved external symbol "public: static char const * const kAPI::Wtyczka::NAME" (?NAME@Wtyczka@1kAPI@@2QBDB)".
Oznaczają one, że linker nie mógł znaleźć definicji tych symboli. Biblioteka kAPI specjalnie nie definiuje ich by programista wtyczki pamiętał o ich ustawieniu. Tak więc ostatnim krokiem będzie inicjalizacja tych pól. Uczynimy to w pliku "mojaWtyczka_kAPI_c.cpp"

#include "mojaWtyczka.h"

const int       Wtyczka::NET           = 12345;
const int       Wtyczka::TYPE          = kAPI::enTypWtyczki::UI;
const char*     Wtyczka::VERSION       = "1.0.0.0";
const char*     Wtyczka::SIG           = "MOJAWTYKA";
const char*     Wtyczka::NAME          = "Moja Wtyczka";
const char*     Wtyczka::NETNAME       = 0;

Co oznacza każdy z tych symboli dla wtyczki przeczytasz tutaj. Na uwagę zasługuje jedynie inicjalizacja pola TYPE. Użyliśmy w tym celu predefiniowanych stałych z przestrzeni kAPI::enTypWtyczki.

I to już wszystko. Prawda, że to łatwe? Zauważ, że nie musiałeś includować żadnych plików z SDK Konnekta.

---

Twórcą projektu kAPI, serwisu oraz materiałów w nim zawartych jest KoSiarz. Kopiowanie zabronione.