Pełną wersję artykułu można pobrać tutaj
Brew – Java, C i C++ w sieciach GSM/GPRS, UMTS i CDMA
BREW – Binary Runtime Environment for Wireless. Platforma została stworzona przez Qualcomm na telefony komórkowe. Początkowo na urządzenia CDMA, później również na urządzenia GSM, UMTS. Platforma jest rozpowszechniona przede wszystkim w Stanach Zjednoczonych. Na urządzenia z platformą BREW można pisać w językach C lub C++. SDK jest darmowe. Obecna wersja BREW API to 3.1.
Przygotowanie środowiska programisty do pracy w BREW
SDK można pobrać z https://brewx.qualcomm.com/brew/sdk/download.jsp. Instalacja odbywa się online w przypadku większości SDK. W systemie operacyjnym ustawiana jest zmienna środowiskowa BREWDIR wskazująca na miejsce, gdzie SDK zostało zainstalowane. W przypadku instalacji kilku SDK należy tę zmienną ustawić jako ścieżkę do aktualnie używanego.
Instalacja SDK Tools
Poza SDK należy zainstalować SDK Tools. Integrują się one z Visual Studio 2003 i Visual Studio 2005. Oprócz narzędzi do Visual Studio zawierają ponadto MIF Editor, Resource Editor. Pozostałe narzędzia dostępne są tylko dla posiadaczy konta w serwisie Qualcomm. Są to BREWToolsSuite – w skład których wchodzą:
• BrewAppLoader – umożliwia zainstalowanie aplikacji na urządzeniu;
• BrewLogger – umożliwia odczytywanie logów aplikacji z urządzenia;
• BrewAppSigner – umożliwia utworzenie paczki gotowej do przejścia procesu podpisu TRUEBREW.
Konfiguracja symulatoradla konkretnego urządzenia
Razem z symulatorem dostarczone są 4 konfiguracje. Dla innych urządzeń konfiguracje można pobrać ze strony Qualcomm.
Kompilatory na urządzenie
Można użyć darmowych narzędzi GCC lub narzędzi ARM – RealView Compilation Tools (RVCT). Po kompilacji uzyskujemy plik ELF (Executeable and Linking Format), który należy przetworzyć pokonsolidacyjnym narzędziem, jako wynik uzyskamy plik MOD. Takie narzędzie udostępniane jest przez Qualcomm – BREWElf2Mod.
Logowanie na urządzeniu
Przydatną funkcją mogącą się przydać podczas debugowania aplikacji jest makro DBGRPINTF . Logi odczytujemy przy pomocy narzędzia dostarczonego przez Qualcomm – BREW Logger. Logi odczytywane są na bieżąco z urządzenia. Warto wspomnieć, że funkcja DBGRPINTF generuje do 128 bajtów na wyjściu – przy dłuższych wpisach należy je podzielić na parę części. W przypadku różnych urządzeń maksymalna ilość bajtów wyjściowych może się różnić.
Producenci urządzeń
Dużo urządzeń wyposażonych w BREW produkują: Audiovox, Kyocera, LG, Motorola, Samsung, UTStarcom. Informacje o urządzeniach, wersjach BREW przez nie wspieranych można znaleźć na stronie Qualcomm: https://brewx.qualcomm.com/brew/sdk/authdownload.jsp?page=devices.
Dodatkowo można tam znaleźć informacje o znanych problemach występujących na urządzeniach i sposobach ich rozwiązania.
Struktura aplikacji
Razem z SDK udostępnione są dwa pliki źródłowe umożliwiające szybkie napisanie aplikacji – są to AEEAppGen.c i AEEModGen.c.
Żeby utworzyć aplikację należy zaimplementować niżej opisane funkcje oraz zdefiniować odpowiednią strukturę, w której obowiązkowo pierwszym polem jest AEEApplet. Poza tym należy przypisać aplikacji unikalny numer.
Deklaracje wymaganych funkcji
Funkcja tworząca zdefiniowaną wcześniej strukturę aplikacji (Listing 2). W tej funkcji należy wywołać metodę (Listing 3). Argumenty funkcji:
• nIn – wielkość struktury aplikacji;
• clsID – unikalny numer aplikacji;
• Jako pIShell oraz pIModule należy przekazać argumenty wejściowe funkcji AEEClsCreateInstance;
• pAppHandleEvent – wskaźnik na funkcję obsługującą zdarzenia przychodzące od systemu.
Parametr application jest wskaźnikiem na zdefiniowaną wcześniej strukturę aplikacji. Wartości pozostałych parametrów funkcji zależą od zdarzenia. Wartość zwracana również powinna zależeć od zdarzenia. Przykładowe zdarzenia to:
• EVT_KEY, EVT_KEY_PRESS, EVT_KEY_RELEASE – wParam – oznacza kod klawisza, dwParam flagi klawiszy modyfikujących;
• EVT_APP_START – wywoływany po starcie aplikacji;
• EVT_APP_CONFIG – wymagany jest start aplikacji z ekranem konfiguracji ( BREW pozwala uruchomić konfigurację programu nie uruchamiając głównej aplikacji);
• EVT_USER – powyżej tego kodu można definiować własne zdarzenia.
Wszystkie zdarzenia opisane są w dokumentacji BREW SDK. pFreeAppData – wskaźnik na funkcję wywoływaną na zakończenie aplikacji, należy w niej zwolnić dane przydzielone aplikacji.
Po wywołaniu funkcji AEEApplet_New możemy utworzyć zdefiniowane przez nas dodatkowe pola struktury aplikacji. Z funkcji AEEClsCreateInstance w przypadku poprawnej inicjalizacji należy zwrócić AEE_SUCCESS w przeciwnym przypadku EFAILED.
Przegląd podstawowych elementów API
Poniżej przedstawione zostały przykładowe części API. Dostęp do tych części uzyskujemy przez interfejsy.
Do tworzenia instancji interfejsów używana jest przede wszystkim funkcja znajdująca się na Listingu 6.
Pierwszy argument to wskaźnik na IShell. Jest to składowa struktury AEEApplet, pierwszego pola zdefiniowanego w strukturze aplikacji. Kiedy potrzebujemy dostępu do tej struktury możemy użyć zdefiniowanego w tym celu makra GETAPPINSTANCE() znajdującego się w nagłówku AEEStdLib.h.
• cls – identyfikator interfejsu którego instancję utworzyć;
• ppobj – adres wskaźnika wskazującego na tworzoną instancję.
Dla większości interfejsów dostępne są funkcje zwalniające zasoby im przydzielone. Zazwyczaj są nazywane IInterface_Release.
Dostęp do plików
Od wersji BREW 3.1 wprowadzono specjalne nazewnictwo ścieżek do plików. Poprzedzenie ścieżki fs:/ oznacza jego użycie. W innym przypadku stosuje się reguły z wcześniejszych wersji, a mianowicie:
• duże znaki zamieniane są na małe;
• backslash ( \ ) konwertowany jest na slash ( / );
• Katalog, w którym umieszczony jest moduł aplikacji traktowany jest jako bieżący i aplikacja ma dostęp tylko do znajdujących się w nim plików. Wyjątkami są ścieżki poprzedzone shared, ringers lub addrbk.
Do operacji na plikach służy IFile. Aby go uzyskać należy wcześniej utworzyć IFileMgr wywołując funkcję ISHELL_CreateInstance z parametrem AEECLSID_FILEMGR. Plik otwiera się funkcją IFILEMGR_OpenFile. Funkcje do podstawowych operacji na plikach:
• IFILE_Read;
• IFILE_Write;
• IFILE_Seek.
Dostęp do ekranu
Aby uzyskać dostęp do ekranu, należy skorzystać z interfejsów IDisplay i IBitmap. Instancje IDisplay uzyskuje się wywołując funkcję ISHELL_CreateInstance z parametrem AEECLSID_DISPLAY. Natomiast, aby uzyskać IBitmap należy użyć funkcji IDISPLAY_GetDeviceBitmap. Informacje o ekranie, takie jak:
• wysokość,
• szerokość,
• ilość kolorów.
Można uzyskać już z IBitmap przez funkcję IBITMAP_GetInfo.
Aby mieć bezpośredni dostęp do tablicy pikseli należy użyć interfejsu IDIB (BREW Device Independent Display). Tworzy się go funkcją IBITMAP_QueryInterface przekazując parametr AEECLSID_DIB jako identyfikator interfejsu. Mając już IDIB można uzyskać wskaźnik na tablicę pikseli poprzez pole pBmp. Po zmianie zawartości tablicy pikseli odświeżenie zawartości ekranu dokonujemy funkcją IDisplay_BitBlt. Pomocnicze funkcje:
• IDISPLAY_DrawText – rysowanie tekstu na ekranie;
• IDisplay_ClearScreen – wyczyszczenie ekranu.
System dźwiękowy
Interfejsem dającym dostęp do systemu dźwiękowego jest IMedia. Instancję można utworzyć na dwa sposoby. Przez funkcję ISHELL_CreateInstance, jeżeli znany jest identyfikator (np. AEECLSID_MEDIAMP3, AEECLSID_MEDIAMIDI, AEECLSID_MEDIAPCM). Drugim sposobem jest użycie udostępnionego narzędzia (AEEMediaUtil.c) i użycie funkcji AEEMediaUtil_CreateMedia. Zaletą drugiego sposobu jest to, że uzyskany w ten sposób interfejs jest gotowy do użycia. W przypadku pierwszego sposobu należy jeszcze wywołać funkcję IMedia_SetMediaData. Do obsługi systemu dźwiękowego dane są między innymi funkcje:
• Imedia_Play;
• Imedia_Stop;
• Imedia_Pause;
• Imedia_Resume;
• Imedia_SetVolume.
Dostęp do sieci
Tutaj używa się przede wszystkim dwóch interfejsów: INetMgr oraz ISocket. Można również skorzystać z ISockPort.
INetMgr uzyskuje się funkcją ISHELL_CreateInstance z parametrem AEECLSID_NET. INetMgr umożliwia utworzenie ISocket oraz odpytanie o adres IP hosta po jego nazwie. Służy do tego metoda INETMGR_GetHostByName. Przekazuje się do niej wskaźnik na funkcję, która zostanie wywołana, kiedy zakończy się zapytanie.
Do utworzenia gniazda stosuje się funkcję INETMGR_OpenSocket. Jednym z argumentów jest typ tworzonego gniazda (TCP lub UDP).
Gniazda w BREW są nieblokujące. Oznacza to, że kiedy system musiałby czekać na możliwość zapisu lub odczytu danych z gniazda, zwraca on kod AEE_NET_WOULDBLOCK, wówczas należy po jakimś czasie ponowić próbę lub można zarejestrować funkcje, które zostaną wywołane, kiedy odczyt/zapis będzie możliwy. W tym celu używa się funkcji: ISOCKET_Readable lub ISOCKET_Writeable. Podstawowe funkcje do operacji na gniazdach:
• ISOCKET_Connect;
• ISOCKET_Read;
• ISOCKET_Write;
• ISOCKET_Bind;
• ISOCKET_Listen;
• ISOCKET_Close.
Struktura plików na urządzeniu
Aby uruchomić aplikację na urządzeniu poza plikiem MOD i plikami używanymi przez aplikację (pliki bar lub inne pliki z zasobami) potrzebny jest plik MIF oraz plik SIG.
Mif editor
W pliku mif znajdują się między innymi informacje o:
• unikalny identyfikator aplikacji (ClassID);
• typ aplikacji;
• ikony;
• jeżeli aplikacja jest rozszerzeniem (extension) wówczas definiowane są eksportowane identyfikatory rozszerzenia (ClassID);
• jeżeli aplikacja używa rozszerzeń, to definiowane są ich identyfikatory;
• prawa udzielone aplikacji;
• wersja.
Plik mif można wygenerować przy pomocy Mif editor i Resource Editor. Oba narzędzia znajdują się w pakiecie SDK Tools.
Generowanie podpisu
Plik podpisu (SIG) do celów testowych można uzyskać ze strony Qualcomu przy pomocy narzędzia TestSig. Podpis generowany jest na konkretny egzemplarz urządzenia (przy generowaniu należy podać jego unikalny numer ESN, MEID lub IMEI).
AppLoader
Po uzyskaniu wszystkich wymaganych do instalacji plików, można zacząć kopiowanie na urządzenie. W tym celu należy podłączyć urządzenie do komputera i połączyć się z nim przy pomocy programu AppLoader. Struktura katalogów na urządzeniu różni się w zależności od wersji platformy.
Przed wersją 3 należy utworzyć katalog o nazwie aplikacji a do niego skopiować wszystkie pliki poza plikiem MIF. Plik MIF należy skopiować do katalogu głównego.
Od wersji 3 katalog z plikami aplikacji tworzymy w katalogu mod, natomiast plik MIF kopiujemy do katalogu mif.
Należy pamiętać o nadaniu plikom MOD, MIF i SIG nazwy takiej samej jak katalog z aplikacją.
Podsumowanie
Po skopiowaniu plików na urządzenie należy je wyłączyć i uruchomić ponownie.
W zależności od typu (ustawienia w pliku MIF) aplikacja może znajdować się w różnych katalogach. Na Listingach 710 została przedstawiona przykładowa aplikacja. Wykorzystuje ona API od ekranu.
W projekcie użyto plików dostarczonych razem z BREW SDK : AEEAppGen.c i AEEModGen.c.
