InsERT GT – Własne COM 1.0
Autor: Jarosław Kolasa, InsERT
Wstęp ... 2
Dołączanie zestawień własnych do systemu InsERT GT ... 2
Sposób współpracy rozszerzeń z systemem InsERT GT ... 2
Rozszerzenia standardowe COM ... 3
Rozszerzenia WSC... 3
Rozszerzenia zrealizowane jako komponenty .NET ... 3
Własne COM – interfejs programisty ... 5
InsERT GT... 5
Interfejs IZestawienieComDane... 5
Zestawienie ... 8
Interfejs IZestawienieWlasne... 8
Wstęp
Niniejszy dokument przeznaczony jest dla twórców aplikacji zintegrowanych z systemem InsERT GT zwanych rozszerzeniami lub zestawieniami własnymi COM. Komunikacja z nimi jest zrealizowana w technologii COM.
Daje to moŜliwość pracy w określonym kontekście systemu InsERT GT, czyli z aktywnym podmiotem, okresem, magazynem, zalogowanym uŜytkownikiem bez konieczności dodatkowego określania tych parametrów. Dodatkowo osiągalne są wszelkie inne informacje z bazy danych oraz moŜliwe jest dowolne kształtowanie interfejsu uŜytkownika.
Ten sposób rozszerzania funkcjonalności systemu InsERT GT nie przewiduje dostępu do jego wewnętrznych obiektów. MoŜliwe są jedynie bezpośrednie operacje na danych w bazie. Zapewniony jest do nich pełny dostęp.
Sposób organizacji danych opisuje osobny dokument – Dokumentacja bazy danych.
Dołączanie zestawień własnych do systemu InsERT GT
Zestawienia wykonane w technologii COM wg specyfikacji moŜna dołączyć do systemu InsERT GT i
wykorzystywać za pomocą modułu Zestawienia. Pozwala on na dodawanie i usuwanie (tylko z programu, a nie z dysku) własnych zestawień wykonanych w technologii COM. W celu dołączenia własnego zestawienia naleŜy wybrać z menu Operacje opcję Dodaj zestawienia COM, a następnie wskazać plik zawierający zestawienie (jedno lub więcej). System wówczas rejestruje wskazane zestawienia i umieszcza na liście dostępnych zestawień własnych o ile zestawienie moŜe być w danym programie uruchamiane (metoda Programy).
Sposób współpracy rozszerzeń z systemem InsERT GT
InsERT GT udostępnia interfejs, za pomocą którego moŜna uzyskać wszystkie informacje na temat kontekstu pracy. Moduł zestawienia dostarczany przez niezaleŜną firmę moŜe zawierać więcej niŜ jedno rozszerzenie.
KaŜde z rozszerzeń musi udostępniać interfejs umoŜliwiający uruchamianie go z InsERT GT (z modułu Zestawienia). Ogólny schemat współpracy przedstawia poniŜszy rysunek.
Uruchomienie dostarczonego zestawienia własnego COM jest moŜliwe po uprzednim zarejestrowaniu tego rozszerzenia w InsERT GT (moŜna to zrobić z poziomu modułu Zestawienia za pomocą opcji Operacje-Dodaj własne COM). Zarejestrowanie polega na zapisaniu informacji w rejestrze systemowym pod kluczem:
<klucz_InsERT_GT>\WlasneCOM\<ProgID_komponentu_rozszerzenia>
InsERT GT
IZestawienieComDane
baza danych podmiotu
Moduł Zestawienia
IZestawienieWlasne
Rozszerzenie/
Zestawienie własne COM
1
IZestawienieWlasne Rozszerzenie/
Zestawienie własne COM
2
IZestawienieWlasne Rozszerzenie/
Zestawienie własne COM
n
następujących trzech wartości ciągu (REG_SZ):
Nazwa nazwa rozszerzenia do wyświetlenia na liście Opis opis realizowanej funkcjonalności rozszerzenia Plik lokalizacja fizyczna kodu rozszerzenia
oraz wartości DWORD (REG_DWORD):
Programy programy, w których ma być widoczne rozszerzenie.
Uruchomienie rozszerzenia polega w pierwszym kroku na stworzeniu przez InsERT GT komponentu o podanym ProgID równym nazwie klucza w rejestrze systemowym. Warunkiem stworzenia takiego obiektu jest oczywiście uprzednie zarejestrowanie w systemie komponentu COM. Kolejnym krokiem przy uruchamianiu rozszerzenia jest wywołanie funkcji Wykonaj i oczekiwanie na jej zakończenie. Wewnątrz funkcji Wykonaj odbywa się zaprogramowana przez twórcę rozszerzenia interakcja z uŜytkownikiem, obliczenie i przedstawianie wyników działania rozszerzenia.
Rozszerzenia standardowe COM
Przy dodawaniu rozszerzeń zrealizowanych jako standardowe komponenty COM z poziomu Zestawień (za pomocą opcji Dodaj), InsERT GT rejestruje je w systemie przez wywołanie funkcji DllRegisterServer z
<nazwa_modułu>.dll. Następnie dodaje je do listy zestawień (rejestruje w InsERT GT). Komponenty, które są zawarte w modułach nieeksportujących tej metody muszą być zarejestrowane poprawnie w systemie przed uruchomieniem opcji Dodaj. MoŜe to realizować np. instalator stworzonego rozszerzenia.
Rozszerzenia WSC
Przy dodawaniu rozszerzeń zrealizowanych jako Windows Script Component z poziomu Zestawień (za pomocą opcji Dodaj), InsERT GT rejestruje je w systemie przez wywołanie funkcji DllInstall z biblioteki scrobj.dll ze wskazaniem na plik WSC. Biblioteka scrobj.dll jest serwerem komponentów skryptowych WSC. Następnie dodaje je do listy zestawień (rejestruje w InsERT GT).
W przypadku komponentów WSC nie jest moŜliwe zaimplementowanie metod jakiegokolwiek interfejsu, w szczególności interfejsu IZestawienieWlasne. W związku z tym dopuszcza się ich realizację jako zwykłych metod obiektu. W procesie uruchamiania zestawienia są one wywoływanych po nazwie za pomocą metod interfejsu IDispatch (GetIDsOfNames, Invoke).
Przy tworzeniu rozszerzeń WSC nieoceniony jest WSC Wizard dostępny pod adresem:
http://msdn.microsoft.com/downloads/sample.asp?url=/msdn-files/027/001/788/msdncompositedoc.xml
Rozszerzenia zrealizowane jako komponenty .NET
Przy dodawaniu rozszerzeń zrealizowanych jako komponenty .NET z poziomu Zestawień (za pomocą opcji Dodaj), InsERT GT dodaje je tylko do listy zestawień (rejestruje w InsERT GT). Dlatego muszą być juŜ wcześniej poprawnie zarejestrowane w systemie. Do tego celu słuŜy narzędzie regasm.exe.
Przykłady wykorzystania regasm.exe do zarejestrowania w systemie własnych zestawień w postaci komponentów .NET zawartych w bibliotece WlasneNET.dll:
A. Zarejestrowanie rozszerzeń w postaci biblioteki prywatnej dla aplikacji:
Krok 1. Skopiowanie WlasneNET.dll do folderu System w miejscu zainstalowania InsERT GT.
Krok 2. Uruchomienie w linii poleceń komendy regasm.exe WlasneNET.dll.
B. Zarejestrowanie rozszerzenia w taki sposób jak inne komponenty COM (wspólne dla całego systemu):
Krok 1. Skopiowanie WlasneNET.dll do dowolnego folderu w systemie plików, gdzie jest moŜliwy dostęp uŜytkowników korzystających z InsERT GT.
Krok 2. Uruchomienie w linii poleceń komendy regasm.exe /c WlasneNET.dll.
UWAGA! Oprócz dystrybucji biblioteki z komponentami WlasneNET.dll naleŜy pamiętać o dostarczeniu równieŜ bibliotek Interop w to samo miejsce (do tego samego folderu). Ich liczba moŜe być róŜna w zaleŜności od zastosowanych rozwiązań. Jednak ze względu na wykorzystanie ADO i biblioteki typów z InsERT GT muszą być przynajmniej dwie: Interop.MSADO15.dll oraz Interop.ZestManLib.dll.
Oczywiście po rejestracji rozszerzeń w systemie naleŜy dokonać odpowiedniego wpisu w rejestrach lub dodać własne zestawienia poprzez Zestawienia-Operacje-Dodaj wlasne COM.
O udostępnianiu klientom COM komponentów .NET więcej moŜna przeczytać pod adresem:
http://msdn.microsoft.com/library/en-us/cpguide/html/cpconexposingnetframeworkcomponentstocom.asp
Własne COM – interfejs programisty
Biblioteka ZestMan.dll dostarczana wraz z InsERT GT zawiera definicje wszystkich interfejsów wykorzystywanych w integracji z rozszerzeniami.
Nazwa UUID Opis
ZestManLib 0DD7E584-C075-4654-9BC8-FC95FEF1F083 InsERT GT ZestMan 1.0 Type Library
InsERT GT
Interfejs udostępniany ze strony InsERT GT.
Nazwa UUID Opis
IZestawienieComDane 6BE4BFFA-694B-49E9-8697-720B88B6830C Informacje o bieŜącym podmiocie i instalacji oraz parametrach poszczególnych programów wchodzących w skład
InsERT GT
Interfejs IZestawienieComDane
Pozwala uzyskać informacje o bieŜącym podmiocie, kontekście pracy i instalacji oraz parametrach poszczególnych programów wchodzących w skład InsERT GT
Connection AO Baza danych bieŜącego podmiotu otwarta przez program (pełny dostęp).
Demo AO Informacja, czy program pracuje w wersji demo.
Program AO Informacja z którego programu uruchomiono zestawienie.
WersjaBazyDanych AO Wersja bazy danych.
FolderProgramu AO Folder programu.
NazwaPodmiotu AO Nazwa podmiotu.
PersonelIdentyfikator AO Identyfikator osoby z personelu zalogowanej do podmiotu.
Personel AO Imię i nazwisko osoby z personelu zalogowanej do podmiotu.
MagazynNazwa AO Nazwa bieŜącego magazynu.
MagazynId AO Identyfikator bieŜącego magazynu.
OkresDataOd AO Początkowa data bieŜącego roku obrachunkowego.
OkresDataDo AO Końcowa data bieŜącego roku obrachunkowego.
DataBlokady AO Data blokady okresu.
A – atrybut, O – do odczytu Atrybut Connection
Zwraca obiekt ADO Connection bieŜącego podmiotu otwarty przez program z pełnymi prawami dostępu.
MoŜliwe są wszelkie operacje wykonywane na bazie danych. Tylko do odczytu.
VC: HRESULT Connection( IDispatch** pVal );
VB: obiekt.Connection As Object Interfejs
IZestawienieComDane Atrybut Demo
Zwraca informację, czy program pracuje jest w wersji demonstracyjnej. Tylko do odczytu.
VC: HRESULT Demo( VARIANT_BOOL* pVal );
Interfejs
IZestawienieComDane Atrybut Program
Zwraca informację, z którego programu uruchomiono zestawienie. Tylko do odczytu.
VC: HRESULT Program( LONG* pVal );
VB: obiekt.Program As Long
Zwracana jest jedna z poniŜszych wartości:
1 - Subiekt
2 - Rachmistrz (KPIR) 4 - Rachmistrz (ryczałt) 8 - mikroGratyfikant Interfejs
IZestawienieComDane Atrybut WersjaBazyDanych
Zwraca informację o wersji bazy danych bieŜącego podmiotu. Tylko do odczytu.
VC: HRESULT WersjaBazyDanych( BSTR* pVal );
VB: obiekt.WersjaBazyDanych As String Interfejs
IZestawienieComDane Atrybut FolderProgramu
Zwraca informację, o miejscu zainstalowania uruchomionego programu. Tylko do odczytu.
VC: HRESULT FolderProgramu( BSTR* pVal);
VB: obiekt.FolderProgramu As String Interfejs
IZestawienieComDane Atrybut NazwaPodmiotu
Zwraca nazwę bieŜącego podmiotu. Tylko do odczytu.
VC: HRESULT NazwaPodmiotu( BSTR* pVal );
VB: obiekt.NazwaPodmiotu As String Interfejs
IZestawienieComDane
Atrybut PersonelIdentyfikator
Zwraca identyfikator osoby z personelu aktualnie zalogowanej do podmiotu. Tylko do odczytu.
VC: HRESULT PersonelIdentyfikator( BSTR* pVal );
VB: obiekt.PersonelIdentyfikator As String Interfejs
IZestawienieComDane Atrybut Personel
Zwraca imię i nazwisko osoby z personelu zalogowanej do podmiotu. Tylko do odczytu.
VC: HRESULT Personel( BSTR* pVal );
VB: obiekt.Personel As String Interfejs
IZestawienieComDane Atrybut MagazynNazwa
Zwraca nazwę bieŜącego magazynu. Tylko do odczytu.
VC: HRESULT Magazyn( BSTR* pVal );
VB: obiekt.Magazyn As String Interfejs
IZestawienieComDane Atrybut MagazynId
Zwraca identyfikator bieŜącego magazynu. Tylko do odczytu.
VC: HRESULT MagazynId( LONG* pVal );
VB: obiekt.MagazynId As Long Interfejs
IZestawienieComDane Atrybut OkresDataOd
Zwraca początkową datę bieŜącego roku obrachunkowego. Tylko do odczytu.
VC: HRESULT OkresDataOd( DATE* pVal );
VB: obiekt.OkresDataOd As Date Interfejs
IZestawienieComDane Atrybut OkresDataDo
Zwraca końcową datę bieŜącego roku obrachunkowego. Tylko do odczytu.
VC: HRESULT OkresDataDo( DATE* pVal );
VB: obiekt.OkresDataDo As Date Interfejs
Atrybut DataBlokady
Zwraca datę blokady okresu. Tylko do odczytu.
VC: HRESULT DataBlokady( VARIANT* pVal );
VB: obiekt.DataBlokady As Variant Atrybut przyjmuje wartość NULL jeśli brak blokady okresu.
Interfejs
IZestawienieComDane
Zestawienie
Interfejs ze strony zestawienia, wykorzystywany do rejestrowania i uruchamiania rozszerzenia przez system InsERT GT.
Nazwa CLSID Opis
IZestawienieWlasne D2B992DB-4C35-440c-AD64-45FFF669DE93 zestawienie własne
Interfejs IZestawienieWlasne
Interfejs, który musi być zaimplementowany przez przez zestawienie własne. Zawiera atrybuty potrzebne do poprawnego zarejestrowania rozszerzenia w systemie InsERT GT oraz metodę do uruchomienia z poziomu modułu Zestawienia.
Opis AO Opis zestawienia.
Nazwa AO Nazwa zestawienia.
Programy AO Programy, w których zestawienie ma być widoczne.
Wykonaj M Uruchamia zestawienie.
A – atrybut, O – do odczytu, M – metoda Atrybut Opis
Opis zestawienia. Tylko do odczytu.
VC: HRESULT Opis( BSTR* pVal );
VB: obiekt.Opis As String Interfejs
IZestawienieWlasne Atrybut Nazwa
Nazwa zestawienia. Tylko do odczytu.
VC: HRESULT Nazwa( BSTR* pVal );
VB: obiekt.Nazwa As String Interfejs
IZestawienieWlasne Atrybut Programy
Zwraca informację, w których programach zestawienie ma być widoczne. Tylko do odczytu.
VC: HRESULT Programy( LONG* pVal );
VB: obiekt.Programy As Long
Zwracana wartość musi być sumą wybranych spośród poniŜszych flag:
1 - Subiekt
2 - Rachmistrz (KPIR) 4 - Rachmistrz (ryczałt) 8 - mikroGratyfikant Interfejs
IZestawienieWlasne Metoda Wykonaj
Uruchamia zestawienie. Wywoływana przez moduł zestawień własnych COM w celu wykonania zestawienia.
VC: HRESULT Wykonaj(IZestawienieComDane * pZestawienieComDane );
VB: obiekt.Wykonaj(pZestawienieComDane As CoZestawienieComDane ) pZestawienieComDane Interfejs IZestawienieComDane do obiektu utworzonego po stronie InsERT GT.
Interfejs
IZestawienieWlasne
Koniec.
