Tworzenie aplikacji Windows Biblioteki DLL. Aplety panelu sterowania (Delphi)

Transkrypt

1 Jacek Matulewski Tworzenie aplikacji Windows Biblioteki DLL. Aplety panelu sterowania (Delphi) Ćwiczenia Toruń, 13 grudnia 2002 Najnowsza wersja tego dokumentu znajduje się pod adresem Źródła opisanych w tym dokumencie programów znajdują się pod adresem 1

2 I. Spis treści I. Spis treści... 2 II. Procedury i funkcje w bibliotekach DLL Tworzenie biblioteki DLL eksport procedur i funkcji Statyczne łączenie bibliotek DLL import funkcji Dynamiczne łączenie bibliotek DLL Powiadamianie biblioteki o załadowaniu jej lub usunięciu z pamięci... 6 III. Formy w bibliotece DLL... 8 IV. Wykorzystanie skompilowanych bibliotek Wykorzystanie biblioteki DLL w Visual Basic Uruchamianie funkcji z linii komend (RunDLL/RunDLL32) V. Aplet panelu sterowania

3 II. Procedury i funkcje w bibliotekach DLL 1. Tworzenie biblioteki DLL eksport procedur i funkcji Najprościej stworzyć bibliotekę DLL (ang. dynamic linked library) korzystając z kreatora ukrytego w menu New..., na zakładce New pod pozycją DLL Wizard (w starszych wersjach Buildera po prostu DLL). Dla naszych potrzeb nie trzeba zmieniać opcji w okienku dialogowym kreatora. Powstanie plik pas rozpoczynający się od słowa kluczowego library. W module możemy zdefiniować procedury i funkcje, a następnie wyeksportować je. Zdefiniujmy pięć najprostszych procedur i funkcji, których jedynym działaniem jest wyświetlanie komunikatów w stylu oto jestem (wywołanie funkcji ShowMessage wymaga dołączenia modułu Dialogs do sekcji uses): procedure Test1; ShowMessage('Test1 - Procedura znajduje sie w bibliotece DLL'); // procedure Test2; StdCall; ShowMessage('Test2 - Procedura znajduje sie w bibliotece DLL'); // procedure Procedura_wewnetrzna; ShowMessage('Procedura_wewnetrzna - Moze byc wywolana tylko przez inny skladnik DLLa'); procedure Test3; StdCall; ShowMessage('Test3 - Wywołanie procedury wewnętrznej'); Procedura_wewnetrzna(); // function Test4(argument :String) :Integer; StdCall; ShowMessage('Test4 - Wywołanie funkcji wewnętrznej'+chr(13)+ 'argument: "'+argument+'"'+chr(13)+'funkcja zwraca liczbe losowa'); Randomize(); Test4:=Random(10000); //zwraca liczbe pseudolosowa Dwie pierwsze procedury (Test1 i Test2) różnią się jedynie modyfikatorem StdCall. Jest on niezbędny gdy procedura ma być wykorzystana przy dynamicznym łączeniu biblioteki w innych platformach 3

4 programistycznych niż Delphi (np. w C++ Builderze) 1 lub gdy procedura przyjmuje jakieś argumenty. Test3 wywołuje funkcję wewnętrzną o nazwie Procedura_wewnetrzna. Procedura ta nie będzie wyeksportowana, a więc nie będzie dostępna z zewnątrz biblioteki, co nie przeszkadza w jej wywołaniu przez inne funkcje z tej samej biblioteki. Wreszcie Test4 jest przykładem wyeksportowanej funkcji przyjmującej argumenty (w naszym przypadku łańcuch) i zwracający wartość (tu będzie to liczba naturalna generowana pseudolosowo). Aby wyeksportować zdefiniowane funkcje należy dodać do kodu sekcję exports, w której umieszczamy listę eksportowanych funkcji. W naszym przypadku jest to: exports Test1 index 1, Test2 index 2, Test3 index 3, Test4 index 4; Po skompilowaniu biblioteki otrzymamy plik z rozszerzeniem DLL. Ważną własnością tego pliku jest jego uniwersalność można go bowiem wykorzystać nie tylko w projektach tworzonych w tym samym środowisku firmy Borland. Jest on zgodny ze specyfikacją bibliotek DLL Windows i może być np. wykorzystany w platformach programistycznych Microsoft Visual C++ lub Visual Basic, a nawet z linii komend za pomocą polecenia RunDLL Statyczne łączenie bibliotek DLL import funkcji Aby dołączyć bibliotekę DLL do aplikacji w sposób statyczny (biblioteka ładowana jest do pamięci zaraz po uruchomieniu aplikacji i pozostaje tam, aż do zakończenia działania programu) należy dodać do sekcji interface modułu aplikacji, w którym importowane funkcje mają być użyte deklaracje (dokładnie odpowiadające deklaracjom tych funkcji w bibliotece DLL): procedure Test1; procedure Test2; StdCall; procedure Test3; StdCall; function Test4(argument :String) :Integer; StdCall; W sekcji implementation zamiast definicji funkcji wystarczy wskazać odpowiednie wejście do biblioteki DLL: procedure Test1; external 'Project1.dll'; procedure Test2; external 'Project1.dll'; procedure Test3; external 'Project1.dll'; function Test4; external 'Project1.dll'; Widać, że słowo kluczowe external zastępuje kod... end implementujący funkcję. Konstrukcja importująca funkcję może być bardziej rozbudowana: procedure Nazwa_procedury; external 'Biblioteka.dll' name Nazwa_procedury_w_DLL index n; Funkcja może być wskazana przez nazwę lub przez indeks. Jeżeli nie korzystamy ani ze słowa kluczowego name, ani z index procedura lub funkcja jest pobierana przez nazwę identyczną jak nazwa zadeklarowanej w module funkcji czy procedury. W ogólności słowo kluczowe pozwala importować funkcję o innej nazwie niż zadeklarowana w module. 1 Dzieje się tak dlatego, że C/C++ nie posiada procedur, które nie pobierają argumentów funkcja C++, nawet jeżeli w kodzie nie pobiera argumentów, w rzeczywistości pobiera argument typu void. Zaś w przypadku procedur z argumentami różna jest kolejność ich przekazywania. 4

5 Stwórzmy nowy pusty projekt i zachowajmy go np. jako Projekt2. Następnie umieśćmy w module (Unit2.pas) powyższe deklaracje i importy funkcji. Możemy teraz bez ograniczeń wykorzystywać funkcje z biblioteki DLL tak, jakby znajdowały się w bieżącym projekcie. Można je na przykład uruchomić naciskając przycisk Button1: procedure TForm1.Button1Click(Sender: TObject); var wynik :Integer; Test1; Test2; Test3; wynik:=test4('przykładowy łańcuch'); ShowMessage('Wynik funkcji Test4: '+IntToStr(wynik)); 3. Dynamiczne łączenie bibliotek DLL Choć łączenie statyczne jest proste, to jednak nie wykorzystuje zalety bibliotek DLL pozwalającej oszczędzać zajmowaną ilość pamięci komputera. W łączeniu dynamicznym biblioteka jest ładowana tylko na czas wykorzystania jej zawartości, potem może być usunięta z pamięci. Łączenie dynamiczne zajmuje nieco czasu, więc nie powinno być wykonywane przed każdym wykorzystaniem często wywoływanej funkcji, bo w znaczący sposób spowolni to działanie programu. Łączenie dynamiczne jest nieco trudniejsze w realizacji, ale za to w pełni wykorzystuje zalety DLL. Jak już wspomniałem można bibliotekę DLL załadować do pamięci i przestrzeni adresowej aplikacji w dowolnym momencie działania tej aplikacji za pomocą funkcji WinAPI LoadLibrary(). Nazwa pliku biblioteki nie musi być znana w momencie kompilacji występuje w funkcji ładującej jedynie jako łańcuch. Każda wyeksportowana funkcja, którą chcemy wykorzystać musi być indywidualnie zaimportowana, a dokładniej aplikacja musi pobrać adres funkcji w swojej przestrzeni adresowej po załadowaniu biblioteki (służy do tego funkcja WinAPI GetProcAddress()). procedure TForm1.Button1Click(Sender: TObject); type //Typy funkcji z DLL DLLTestType = procedure; DLLTestType4 = function(argument :String) :Integer; StdCall; //Tu ma znaczenie StdCall bo pojawia sie argument var DLLHandle :THandle; ATest1,ATest2,ATest3 :DLLTestType; ATest4 :DLLTestType4; wynik :Integer; DLLHandle:=LoadLibrary('Project1.dll'); if (DLLHandle<>0) then ShowMessage('Wczytanie biblioteki udało się') else ShowMessage('Wczytanie biblioteki nie powiodło 'Test3'); if (@ATest1=nil) then ShowMessage('Uruchomienie Test1 nie jest możliwe') else ATest1; if (@ATest2=nil) then ShowMessage('Uruchomienie Test2 nie jest możliwe') else ATest2; 5

6 if then ShowMessage('Uruchomienie Test3 nie jest możliwe') else 'Test4'); if then ShowMessage('Uruchomienie Test4 nie jest możliwe') else wynik:=atest4('przykładowy łańcuch'); ShowMessage('Wynik funkcji Test4: '+IntToStr(wynik)); if (FreeLibrary(DLLHandle)) then ShowMessage('Usunięcie biblioteki z pamięci udało się') else ShowMessage('Usunięcie biblioteki z pamięci nie powiodło się'); Jak wspominałem wcześniej dynamiczne łączenie biblioteki realizowane jest przez funkcję WinAPI LoadLibrary() pobierającą nazwę biblioteki, a zwracającą, jeżeli połączenie się powiodło, uchwyt do tej biblioteki (uchwyt może być przechowywany w zmiennej typu THandle). Podanie samej nazwy biblioteki bez jego ścieżki jest wygodne, gdyż umożliwia to swobodne przemieszczanie pliku biblioteki między katalogiem aplikacji lub katalogiem bieżącym w trakcie jej projektowania aplikacji, a katalogiem systemowym (WINDOWS\SYSTEM), katalogiem głównym Windows lub wreszcie innym katalogiem wymienionym w zmiennej środowiskowej PATH po jej zainstalowaniu. Do trzech zmiennych proceduralnych 2 ATest1 ATest3 pobierane są adresy funkcji Test1 Test3. W przeciwieństwie do C++ Buildera w przypadku procedur nie pobierających argumentów modyfikator StdCall nie ma żadnego znaczenia w Delphi. Zmienna proceduralna wykorzystywana jest identycznie jak nazwa funkcji. Wstawienie jej do kodu spowoduje wywołanie przechowywanej przez zmienną procedury. Można w identyczny sposób jak w przypadku zwykłej funkcji podawać argumenty. Modyfikator StdCall musi się pojawić w deklaracji funkcji Test4 ze względu na argument. Brak modyfikatora spowoduje wywołanie wyjątku EAccessViolation. Zwolnienie biblioteki możliwe jest dzięki funkcji WinAPI FreeLibrary(), której argumentem jest uchwyt do biblioteki. 4. Powiadamianie biblioteki o załadowaniu jej lub usunięciu z pamięci Można sobie wyobrazić bardziej skomplikowane od naszego wykorzystanie bibliotek DLL, która na przykład przy jej załadowaniu musi zainicjować zmienne globalne, tworzyć obiekty itp. Niezbędna do tego jest funkcja inicjująca, analogiczna do konstruktora obiektu oraz odpowiednik destruktora przy usuwaniu biblioteki z pamięci. Zgodnie ze specyfikacją WinAPI w bibliotece może znajdować się funkcja zwrotna o nazwie DllEntryPoint, która będzie wywoływana przez system w momencie ładowania i usuwania biblioteki z pamięci. W Delphi realizuje się to jednak nieco inaczej. W module System zadeklarowana jest zmienna o nazwie DLLProc typu proceduralnego TDLLProc = procedure (Reason: Integer); przyjmująca jeden argument naturalny. Jeżeli do tej zmiennej przypisana jest procedura, to jest ona wywoływana w momencie usunięcia biblioteki z pamięci oraz podłączenia jej lub odłączenia od wątku. W trakcie podłączania biblioteki nie jest wywoływana, ale w obrębie biblioteki może znajdować się sekcja... end., w której można umieścić dowolny kod np. uruchomienie DLLProc z odpowiednim argumentem. Często deklaruje się procedurę przypisywaną do DLLProc pod nazwą DllEntryPoint, ale nie jest to konieczne. 2 Wygodnie jest, jak zrobiono w tym przykładzie, zdefiniować typy dla importowanych typów funkcji 6

7 Zatem na końcu pliku biblioteki Project1.pas między i end dodajemy przypisanie procedury do zmiennej DLLProc oraz wywołujemy tą procedurę z argumentem oznaczającym włączenie biblioteki do przestrzeni adresowej aplikacji: ShowMessage('Biblioteka Project1.dll (kod główny biblioteki)'); DLLProc:=@DllEntryPoint; DllEntryPoint(DLL_PROCESS_ATTACH); end. Argument reason może przyjmować cztery wartości określone przez następujące stałe: DLL_PROCESS_ATTACH / DLL_PROCESS_DETACH gdy biblioteka jest włączona/wyłączona z wirtualnej przestrzeni adresowej procesu 3. Zdarza się to przy uruchomieniu/zamknięciu aplikacji (przy włączeniu jeszcze przed pokazaniem formy), jeżeli biblioteka jest ładowana statycznie i przy każdym wywołaniu LoadLibrary()/FreeLibrary() w przypadku ładowania dynamicznego. DLL_THREAD_ATTACH / DLL_THREAD_DETACH analogicznie jak wyżej, ale po utworzeniu przez proces wątku. procedure DllEntryPoint(reason :Cardinal); case (reason) of DLL_PROCESS_ATTACH: ShowMessage('DllEntryPoint - DLL_PROCESS_ATTACH '); DLL_PROCESS_DETACH: ShowMessage('DllEntryPoint - DLL_PROCESS_DETACH '); DLL_THREAD_ATTACH: ShowMessage('DllEntryPoint - DLL_THREAD_ATTACH '); DLL_THREAD_DETACH: ShowMessage('DllEntryPoint - DLL_THREAD_DETACH '); Po zmodyfikowaniu biblioteki (Project1) możemy sprawdzić kiedy inicjowana jest biblioteka przy statycznym (Project2) i dynamicznym jej dołączaniu (Project3). Warto zauważyć, że po zmianie biblioteki, właściwa aplikacja nie musi być nawet przekompilowywana. 3 W Win32 każdy proces ma osobną wirtualną przestrzeń adresową o wielkości 4GB, w odróżnieniu od wspólnej przestrzeni adresowej Win16. 7

8 III. Formy w bibliotece DLL. Korzystając z TDiskInfoPanel i przykładu IV.3 w części WinAPI napiszemy i umieścimy w bibliotece DLL formę pokazującą informacje o dyskach zainstalowanych w komputerze. Skopiujmy plik DiskInfo.pas zawierająca definicję i deklarację klasy TDiskInfoPanel. Stwórzmy bibliotekę DLL (New..., DLL) i dołączmy do niej te pliki (do sekcji uses należy dodać DiskInfo). Wygodne będzie przechowywanie globalnego (w obrębie modułu) wskaźnika do formy, zadeklarujmy więc zmienną typu wskaźnika do TForm: var DIPForm :TForm; Niezbędne będzie dodanie do uses modułu Forms. Ponadto potrzebujemy dwóch procedur tworzącej formę i usuwającej ją z pamięci. Pierwsza procedura procedure DIP_CreateForm(modal :Boolean) tworzy formę bez właściciela: DIPForm:=TForm.Create(nil); i zapisuje ją do zmiennej globalnej DIPForm. Następnie wykonywany jest kod, który jest kopią poleceń z Unit1.pas znajdującego się w przywołanym wyżej przykładzie WinAPI.IV.3 (zastąpiono jedynie Form1 przez DIPForm). I wreszcie na koniec pokazywana jest forma w sposób zależny od argumentu całej funkcji (modalnie tzn. uniemożliwiając dostęp do aplikacji zanim nie zostanie zamknięte wywołane okno lub jako zwyczajne okno): if (modal) then DIPForm.ShowModal else DIPForm.Show; Druga funkcja DIP_DestroyForm() najpierw zamyka formę, a następnie usuwa ją z pamięci (DIPForm.Free();). Istotne jest też przypisanie na powrót wskaźnikowi wartości nil. Uwaga! Prototypy obu form zostały napisane tak, żeby możliwe było ich uruchomienie przy dynamicznym załadowaniu biblioteki. Równocześnie pozwala to na używanie biblioteki z tymi funkcjami w innych aplikacjach, a także uruchamianie ich bezpośrednio z linii komend (zob. poniższe paragrafy). Oto kompletny kod biblioteki DLL: library Project1; uses SysUtils, Classes, Forms, //potrzebne do TForm DiskInfo; //zawiera TDiskInfoPanel var DIPForm :TForm; //Tworzenie formy procedure DIP_CreateForm(modal :Boolean); StdCall; const drvletterno=ord('z')-ord('a')-1; margines=10; var litera :Char; n, drvno :Integer; DiskInfoPanel :array[0..drvletterno-1] of TDiskInfoPanel; 8

9 polozenie_ostatniego :Integer; if (DIPForm<>nil) then if (modal) then DIPForm.ShowModal else DIPForm.Show; Exit; DIPForm:=TForm.Create(nil); DIPForm.Caption:='Informacja o dyskach'; DIPForm.Position:=poScreenCenter; polozenie_ostatniego:=0; n:=0; drvno:=0; for litera:='a' to 'z' do DiskInfoPanel[n]:=TDiskInfoPanel.Create(DIPForm); DiskInfoPanel[n].Left:=margines; DiskInfoPanel[n].DriveLetter:=litera; if (DiskInfoPanel[n].Values.disk_accesible) then DiskInfoPanel[n].Parent:=DIPForm; DiskInfoPanel[n].Top:= margines+drvno*(diskinfopanel[n].height+round(1.5*margines)); polozenie_ostatniego:=diskinfopanel[n].top+diskinfopanel[n].height; DIPForm.ClientWidth:=DiskInfoPanel[n].Width; Inc(drvno); end else DiskInfoPanel[n].Free(); DiskInfoPanel[n]:=nil; DIPForm.ClientHeight:=polozenie_ostatniego+margines; if (modal) then DIPForm.ShowModal else DIPForm.Show; //Usuwanie formy procedure DIP_DestroyForm; StdCall; if (DIPForm<>nil) then DIPForm.Close(); DIPForm.Free(); DIPForm:=nil; exports DIP_CreateForm, DIP_DestroyForm; DIPForm:=nil; end. 9

10 Uwaga! Proszę zwrócić uwagę, że zamknięcie okna nie powoduje usunięcia go z pamięci. Po zamknięciu okna na i zniknięciu jego reprezentacji graficznej na ekranie (albo przez użytkownika, albo metodą DIPForm.Close()) obiekt formy istnieje i wskaźnik jest różny od NULL. Dlatego na samym początku procedury DIP_CreateForm umieszczono warunek: if (DIPForm<>nil) then if (modal) then DIPForm.ShowModal else DIPForm.Show; Exit; chroniący przed ponownym tworzeniem obiektu. Jeżeli forma istnieje jest po prostu pokazywana. Inaczej powstałaby nowa forma, której wskaźnik zostałby zapisany do DIPForm, a do starej stracilibyśmy dostęp. Teraz zajmiemy się aplikacją, która posłuży do przetestowania biblioteki (menu New Application). Zapiszmy ją do tego samego katalogu co bibliotekę DLL jako Project2 i Unit2. Z przyciskami zwiążemy funkcje wyeksportowane w bibliotece: procedure TForm1.Button1Click(Sender: TObject); DIP_CreateForm(CheckBox1.Checked); // procedure TForm1.Button2Click(Sender: TObject); DIP_DestroyForm; 10

11 IV. Wykorzystanie skompilowanych bibliotek Stworzona w poprzednim paragrafie biblioteka DLL posłuży teraz jako przykład przenaszalności skompilowanej biblioteki na inne platformy programistyczne. Należy pamiętać o jej skopiowaniu do katalogu projektów lub, czego raczej nie polecam, do katalogu Windows. 1. Wykorzystanie biblioteki DLL w Visual Basic Istotną zaletą skompilowanej biblioteki DLL jest możliwość wykorzystania jej w dowolnym innym kompilatorze. Warunkiem jest wykorzystanie modyfikatorów umożliwiających ładowanie dynamiczne wyeksportowanych funkcji przez funkcję LoadLibrary(). Dla przykładu wywołajmy funkcję z naszej biblioteki DIP_CreateForm() z aplikacji napisanej w Visual Basicu. Informacje o wykorzystywaniu bibliotek DLL w Visual Basicu 6.0 można znaleźć w MSDN 4 Na początku musimy zadeklarować importowane funkcje w sekcji General, Declarations: Private Declare Sub DIP_CreateForm Lib "Project1" (ByVal modal As Boolean) Private Declare Sub DIP_DestroyForm Lib "Project1" () Uwaga! W Visual Basicu, w przeciwieństwie do C++ istnieje rozróżnienie między funkcjami i procedurami/subroutinami. Wobec tego, ponieważ nasze funkcje nie zwracają wartości, muszą być zadeklarowane słowem kluczowym Sub, a nie Function. Zapomnienie o tym będzie powodowało zgłaszanie błędów i wadliwe działanie aplikacji. Teraz możemy wywołać je w procedurach związanych z naciśnięciem klawiszy (zawartość formy powinna być identyczna jak w poprzednim paragrafie): Private Sub Command1_Click() DIP_CreateForm Check1.Value End Sub Private Sub Command2_Click() DIP_DestroyForm End Sub 2. Uruchamianie funkcji z linii komend (RunDLL/RunDLL32) W katalogu systemowym Windows (WINDOWS\SYSTEM32) znajduje się program RunDLL32.exe umożliwiający uruchamianie programów umieszczonych w bibliotekach DLL. Ponieważ wykorzystuje on funkcję WinAPI LoadLibrary() funkcje muszą pozwalać na ładowanie dynamiczne, tzn. powinny być zadeklarowane z odpowiednimi modyfikatorami np.: extern "C" declspec(dllexport) void stdcall DIP_CreateForm(bool); Składnia tego programu jest następująca: RUNDLL.EXE <dllname>,<entrypoint> <optional arguments> 4 Odpowiedni paragraf: MSDN Home > MSDN Library > Visual Basic 6.0 > Component Tools Guide (Pro, Enterprise only) > Accessing DLLs and the Windows API > Using a DLL Procedure in Your Application 11

12 W naszym przypadku musimy napisać: RunDLL32.exe Project1.dll,DIP_CreateForm 0 12

13 V. Aplet panelu sterowania Mając gotową bibliotekę DLL zawierającą klasę formy lub, jak jest w naszym przypadku, tworzącą dynamicznie formę możemy w kilku krokach uzyskać aplet panelu sterowania. Aplet taki jest w istocie biblioteką DLL zawierającą wyeksportowaną funkcję zwrotną o nazwie CPlApplet() i zmienionym rozszerzeniem nazwy pliku na.cpl. To jest jedyna funkcja za pomocą której Panel sterowania kontaktuje się z biblioteką. Zastępuje ona standardowe wejście do biblioteki. Funkcja zwrotna CPlApplet() zadeklarowana jest w WinAPI jako LONG APIENTRY CPlApplet(HWND hwndcpl, UINT umsg, LONG lparam1, LONG lparam2); Tłumacząc to na standardowy język C++ można deklarację przepisać jako 5 long stdcall CPlApplet(THandle hwndcpl, unsigned umsg, long lparam1, long lparam2); Natomiast korzystając z typów zdefiniowanych w Delphi (a także w module CPl, który należy dodać do uses): function CPlApplet(hwndCPl :THandle; umsg :Cardinal; lparam1, lparam2 :LongInt) :LongInt; StdCall Należy pamiętać, że CPlApplet(), w przeciwieństwie do DllEntryPoint() z poprzednich paragrafów musi być wyeksportowana, tj. należy dodać ją do sekcji exports: exports DIP_CreateForm, DIP_DestroyForm, CPlApplet; W opisie funkcji posłużę się przykładami kodu, w którym zdefiniuję jeden aplet, wywołujący znane nam z poprzednich paragrafów okienko prezentujące informacje o dyskach w postaci pasków postępu z odpowiednimi opisami. Wykorzystamy napisane wcześniej funkcje DIP_CreateForm i DIP_DestroyForm. W cyklu życia apletu funkcja CPlApplet jest wywoływana wielokrotnie z różnymi argumentami w celu wymiany informacji między apletem a systemem. Typ i nazwa argumentów ma kojarzyć się z komunikatami Windows. Ich rodzaj zależy od żądanych od apletu informacji. Jako pierwszy wysyłany jest komunikat CPL_INIT, który jest czymś w rodzaju pytania od Panelu sterowania: Czy jesteś apletem?. Zwrócona wartość powinna być true, jeżeli chcemy, aby aplet został umieszczony wśród innych apletów Panelu sterowania i żeby wysyłane były kolejne komunikaty. function CPlApplet(hwndCPl :THandle; umsg :Cardinal; lparam1, lparam2 :LongInt) :LongInt; StdCall var lpcpli :^CPLINFO; case (umsg) of CPL_INIT: CPlApplet:=Ord(True); //potwierdzamy, ze jestesmy apletem Exit; 5 Modyfikator APIENTRY jest tożsamy z modyfikatorem WINAPI w kontekście bibliotek DLL, a ten ostatni dla środowiska 32-bitowego jest równoznaczny z stdcall, a więc oznacza standardowy sposób wywoływania funkcji i przekazywania do niej argumentów (ang. standard calling convention). W takim przypadku kompilator nie dodaje znaków podkreślenia przed nazwą funkcji, zachowuje wielkość liter, argumenty muszą być w zadeklarowanej ilości i bezwzględnie identycznego typu. 13

14 else CPlApplet:=0; Exit; Kolejny komunikat to CPL_GETCOUNT, który jest pytaniem o ilość apletów przechowywanych w bibliotece. Odpowiedzią powinna być zwrócona przez wartość funkcji równa ilości apletów, które chcemy udostępnić. Kolejne komunikaty przekazywane są tyle razy, ile zadeklarowaliśmy apletów. CPL_GETCOUNT: if (sm) then ShowMessage('CPL_GETCOUNT'); CPlApplet:=1; //ilosc okien dialogowych Exit; W następnych komunikatach CPL_INQUIRE i CPL_NEWINQUIRE Panel sterowania żąda informacji o ikonie, tytule i podpowiedzi (hint) apletu. W obu przypadkach do CPlApplet() przesyłane są wskaźniki do struktur umożliwiających zwrot odpowiednich informacji. Wygodniej jest wykorzystać CPL_NEWINQUIRE, ponieważ przekazywana do niego struktura jest wygodniejsza w obsłudze i nie wymaga dodawania plików zasobów. Na przekór lenistwu skorzystamy z trudniejszego w obsłudze CPL_INQUIRE. Parametry przesyłane z tą wiadomością są następujące: UNIT uappnum=(uint)lparam1; CPLINFO* lpcpli=(lpcplinfo)lparam2; Pierwszy to numer okna dialogowego / apletu komunikat jest wysyłany raz dla każdego zadeklarowanego apletu (numerowanych od 0). Drugi to wskaźnik do struktury CPLINFO, która zawiera trzy składniki int: idicon, idname, idinfo oraz jeden typu long ldata. Pierwsze trzy są numerami identyfikującymi elementy zasobów (zawartych w dołączonym do projektu pliku.res). Po kolei są to numery ikony apletu, tytułu i treści podpowiedzi. Ostatnia dana ldata to liczba którą przechowuje Panel sterowania i przekazuje w argumentach razem z komunikatami CPL_DBLCLK i CPL_STOP. Pomaga to czasami w programowaniu pozwalając na przechowanie informacji ponieważ biblioteka nie jest cały czas załadowana, jej zmienne lokalne mogą być usunięte. Stworzenie pliku zasobów nie jest zbyt dobrze wspierane przez Borland C++ Builder/Delphi. Obcecny w IDE Image Editor pozwala na umieszczanie w plikach.res ikon, bitmap i kursorów, ale nie wspiera umieszczania tam łańcuchów. A Windows pozwala na o wiele więcej (klawisze skrótów, okna dialogowe, kod HTML, menu i informacje o wersji aplikacji). Aby umieścić pozostałe informacje należy się posłużyć narzędziami linii komend BRCC32.EXE (Borland Resource Compiler) lub wygodnymi narzędziami konkurencyjnego Visual C++. Wybierzmy ponownie trudniejszą drogę i stwórzmy plik zasobów zawierających odpowiednie ikony i łańcuchy. Należy stworzyć plik o rozszerzeniu.rc (np. DiskInfo.rc), w którym wskażemy na pliki zawierające ikony i podamy łańcuchy z odpowiednimi identyfikującymi je numerami: STRINGTABLE { //tytul apletu 1, "Informacje o dyskach" //opis apletu (okienko podpowiedzi) 2, "Informacje o wielkości, ilości wolnego miejsca, typu FAT dysków lokalnych, CD-ROMów i dysków sieciowych" } //ikona jest wczytywana z pliku Project1.ico 101 ICON Project1.ico 14

15 a następne skompilować poleceniem brcc32.exe DiskInfo.rc. Powstanie plik DiskInfo.res, którego format jest zgodny ze standardem plików z zasobami. Uwaga! Linia zaczynająca się od 2, "Informacje o i następna powinna znajdować się w jednej linii. Mając plik zasobów res możemy włączyć go do projektu (Projet, Add to project...) i zareagować na komunikat CPL_INQUIRE: CPL_INQUIRE: lpcpli:=pointer(lparam2); //wskaznik do CPLINFO lpcpli.idicon:=101; lpcpli.idname:=1; lpcpli.idinfo:=2; lpcpli.ldata:=0; CPlApplet:=0; Exit; Ignorujemy pierwszy parametr przekazujący numer apletu, ponieważ w naszej bibliotece jest tylko jeden aplet (jeden zadeklarowaliśmy przy GET_COUNT) i ten komunikat będzie przekazany do biblioteki tylko jeden raz. Musimy wcześniej zadeklarować, najlepiej z zasięgiem ograniczonym do funkcji CPlApplet, wskaźnik var lpcpli :^CPLINFO;. Przypisanie do idicon, idname i idinfo wartości zdefiniowanej w stałej CPL_DYNAMIC_RES spowoduje wywoływanie CPL_NEWINQUIRE przy każdym wyświetleniu ikony. Jest to sposób umożliwiający zmianę ikony w zależności od stanu komputera. Niestety, jak twierdzi MS Win32 SDK, znacznie zwalnia to działanie Panelu sterowania 6. W praktyce korzysta się zazwyczaj z tego komunikatu zamiast CPL_INQUIRE, ponieważ nie wymaga on pliku zasobów (pozwala na podawanie tekstu tytułu i podpowiedzi w postaci zwykłego łańcucha i ikony poprzez uchwyt). Oba komunikaty powinny powodować zwracanie przez CPlApplet() wartość 0, co informuje Panel sterowania o powodzeniu. Po wysłaniu tych komunikatów funkcja CPlApplet() jest wywoływana dopiero wtedy, gdy użytkownik usiłuje otworzyć odpowiedni aplet klikając dwukrotnie na jego ikonę w Panelu sterowania. Wysyłany jest wówczas komunikat CPL_DBLCLK. Reakcja na niego powinna się wiązać z wywołaniem okienka dialogowego. My po prostu wywołamy zdefiniowaną w poprzednich paragrafach funkcję DIP_CreateForm(). CPL_DBLCLK: DIP_CreateForm(true); //musi byc true modalne CPlApplet:=0; Exit; Podobnie jak w poprzednim wywołaniu CPlApplet, jeżeli wszystko się powiodło informujemy o tym panel sterowania zwracając zero. Forma musi być wywołana modalnie inaczej po jej pokazaniu zostanie zaraz zamknięta nic nie zatrzymuje wysyłanie kolejnych komunikatów i usunięcia biblioteki z pamięci 7. I wreszcie, po zamknięciu formy przez użytkownika zostaną wysłane dwa komunikaty CPL_STOP i CPL_EXIT. Jeden z nich powinien dla porządku usunąć formę z pamięci (zamknięcie okna nie powoduje usunięcia jej obiektu, ale i tak usunięty zostałby przy odłączaniu biblioteki). CPL_EXIT: DIP_DestroyForm(); 6 Przy mocy dzisiejszych komputerów nie ma to chyba większego znaczenia. 7 Jeżeli nie tworzymy formy dynamicznie, a mamy klasę formy w bibliotece powinna mieć własność Visible ustawioną na false. Inaczej próba wywołania ShowModal() skończy się błędem. 15

16 CPlApplet:=0; Exit; Teraz trzeba skompilować projekt, a plik wynikowy Project1.dll przemianować na przykład na Project1.cpl. Ten plik należy skopiować do katalogu systemowego Windows (C:\WINDOWS\SYSTEM lub C:\WIN2000\SYSTEM32 w zależności od wersji systemu). Jeżeli nie popełniliśmy żadnego błędu w oknie Panelu sterowania pojawi się nowa ikona, której kliknięcie pokaże informacje o dyskach. 16