Be Book Application Kit Application Kit Indeks

BRoster

Pochodzi od : żaden
Zadeklarowany w:  be/app/Roster.h
Biblioteka: libbe.so
Podsumowanie:  więcej...

 

Obiekt BRoster reprezentuje usługę, która utrzymuje spis wszystkich aplikacji aktualnie działających. Może ona dostarczać informacji o tych aplikacjach, aktywować je, dodawać inne aplikacje do spisu przez ich uruchomienie lub podawać informacje o aplikacji aby pomóc Ci zadecydować czy ją uruchomić.

Jest tylko jeden spis i jest on współdzielony przez wszystkie aplikacje. Gdy aplikacja uruchamia się, konstruowany jest obiekt BRoster i przypisywany do globalnej zmiennej be_roster. Masz zawsze dostęp do spisu poprzez tą zmienną; nigdy nie musisz tworzyć egzemplarza BRoster'a w kodzie aplikacji.

BRoster identyfikuje aplikacje na trzy sposoby:

Jeśli aplikacja jest uruchomiona więcej niż raz, spis będzie będzie zawierać jeden zapis dla każdego egzemplarza aplikacji, która już działa. Te egzemplarze będą miały takie same sygnatury ale różne identyfikatory zespołu.


Konstruktor i Destruktor


BRoster()

BRoster(void)

Ustawia połączenie obiektu dousługi spisu.

Gdy aplikacja konstuuje swój obiekt BApplication, system konstruuje obiekt BRoster i przypisuje go do zmiennej globalnej be_roster. BRoster jest więc łatwo dostępny od chwili gdy aplikacja jest inicjalizowana aż do czasu jej zamknięcia; nie musisz go konstuować. Konstruktor jest publiczny tylko jest ogólnie dostępny tylko po to aby tym programom, które nie mają obiektu BApplication dać dostęp do spisu.


~BRoster()

~BRoster()

Nic nie robi.


Funkcje Członkowskie


ActivateApp()

status_t ActivateApp(team_id team) const

Aktywuje aplikację team (przez przestawienie jej okien do przodu i uczynienie jej okna aktywnym). Ta funkcja działa tylko jeśli docelowa aplikacja ma okno na ekranie. Niedawno wywołana aplikacja jest powiadamiana przy pomocy komunikatu B_APP_ACTIVATED.

Popatrz także do: BApplication::AppActivated()


AddToRecentDocuments() , GetRecentDocuments()

void AddToRecentDocuments(const entry_ref *document,
      const char *appSig = NULL) const
void GetRecentDocuments(BMessage *refList, int32 maxCount,
      const char *ofType = NULL,
      const char *openedByAppSig = NULL) const
void GetRecentDocuments(BMessage *refList, int32 maxCount,
      const char *ofTypeList[] = NULL, int32 ofTypeListCount,
      const char *openedByAppSig = NULL) const

AddToRecentDocuments() dodaje plik dokumentu określonego przez parametr document do listy niedawno używanych dokumentów. Jeśli życzysz sobie zapisać że określona aplikacja używała dokumentu, możesz określić sygnaturę tej aplikacji używając argument appSig; w przeciwnym wypadku możesz określić NULL.

GetRecentDocuments() zwraca listę najczęściej niedawno używanych dokumentów. Parametr refList typu BMessage będzie wypełniony informacjami o liczbie równej maxCount najczęściej niedawno używanych dokumentów. Jeśli chcesz uzyskać listę dokumentów określonego typu, możesz określić wskaźnik do łańcucha tego typu MIME w argumencie ofType. Podobnie, jeśli jesteś zainteresowany plikami które chcesz aby zostały otwarte przez określoną aplikację, określ syganturę aplikacji w openedByAppSig; jeśli nie dbasz o to, przekaż NULL.

Jeśli chcesz dostać listę plików wielu typów, mośzesz określić wskaźnik do tablicy łańcuchów zanków parametrze ofTypeList a liczbę typów w liście w parametrze ofTypeListCount.

Określenie NULL dla parametru ofType będzie pobierać wszystkie pliki wszystkich typów.

Wynikowa lista refList będzie mieć pole "refs", zawierające parametry entry_ref do wynikowej listy plików.


AddToRecentFolders() , GetRecentFolders()

void AddToRecentFolders(const entry_ref *folder,
      const char *appSig = NULL) const
void GetRecentFolders(BMessage *refList, int32 maxCount,
      const char *openedByAppSig = NULL) const

AddToRecentFolders() dodaje folder określony przez parametr folder do listy najczęściej używanych folderów. Jeśli życzysz sobie zapisac która określona aplikacja używała folderu, możesz okreśić sygnaturę tejaplikacji używając argumentu appSig; w przeciwnym wypadku możesz użyć NULL.

GetRecentFolders() zwraca listę najczęściej używanych folderów. Parametr refList typu BMessage będzie wypełniony informacjami o o liczbie równej maxCount najczęściej używanych folderów. Jeśli jesteś zainteresowany folderami któe były używane przez określoną aplikację, określ sygnaturę tej aplikacji w parametrze openedByAppSig; jeśli nie dbasz o to, przekaż NULL.

Wynikowa lista refList będzie mieć pole "refs", zawierające parametry entry_ref do wynikowej listy folderów.


Broadcast()

status_t Broadcast(BMessage *message) const
status_t Broadcast(BMessage *message, BMessenger reply_to) const

Wysyła komunikat message do każdej działąjącej aplikacji, za wyjątkiem tych aplikacji (B_ARGV_ONLY) które nie akceptują komunikatów. Komunikat jest wysyłany asynchronicznie z przerwą czasową równą 0. Jak to jest w przypadku innych funkcji wysyłąjących komunikaty, wywołujacy zachowuje prawo własności do komunikatu message.

Ta funkcja zwraca wartość natychmiast po zestawieniu operacji rozgłaszania. Nie czeka ona na wysłanie komunikatów i nie informuje o napotkanych błędach gdy one wystąpią. Zwraca ona błąd tylko jeśli nie mogła rozpocząć operacji rozgłaszania. Jeśli zakończyła się sukcesem podczas rozpoczęcia operacji, to zwraca wartość B_OK.

Odpowiedzi na rozgłoszone komunikaty będą wysyłane poprzez prarametr reply_to typu BMessenger, jeśli go określono. Jeśli parametr reply_to jest nieobecny, odpowiedzi będa zagubione.

Popatrz także do: BMessenger::SendMessage()


FindApp()

status_t FindApp(const char *type, entry_ref *app) const
status_t FindApp(entry_ref *file, entry_ref *app) const

Znajduje aplikację przypisaną do danych MIME type lub z określonym plikiem file i modyfikuje strukturę zmiennej app typu entry_ref żeby się odnosiła do pliku wykonywalnego dla tej aplikacji. Jeśli zmienna type jest sygnaturą aplikacji, ta funkcja znajduje aplikację , która ma tą sygnaturę. W przeciwnym wypadku znajduje ona aplikację preferowaną dla tego typu. Jeśli zmienna file jest aplikacją wykonywalną, FindApp() kopiuje tylko odniesienie pliku do argumentu app. W przeciwnym wypadku znajduje ona aplikację preferowaną dla tego typue.

Inaczej mówiąc, ta funkcja chodzi dookoła, znajdując aplikację w ten sam sposób, w który funkcja Launch() znajduje aplikację, którą będzie uruchamiać.

Jeżeli może ona przetłumaczyć typ type lub plik file do odniesienia do aplikacji wykonywalnej, FindApp() zwraca wartość równą B_OK. Jeśli nie, to zwraca ona kod błędu, zwykle opisując błąd systemu plików.

Popatrz także do: Launch()


GetAppInfo() , GetRunningAppInfo() , GetActiveAppInfo()

status_t GetAppInfo(const char *signature, app_info *appInfo) const
status_t GetAppInfo(entry_ref *executable, app_info *appInfo) const
status_t GetRunningAppInfo(team_id team, app_info *appInfo) const
status_t GetActiveAppInfo(app_info *appInfo) const

Te funkcje zwracają (w appInfo) informację o określonej aplikacji. We wszystkich przypadkach, aplikacja musi działać.

Jeśli jest ona zdolna do wypełnienia znaczących wartości w strukturze app_info, te funkcje zwracają B_OK. GetActiveAppInfo() zwraca B_ERROR jeśli nie ma aktywnej aplikacji. GetRunningAppInfo() zwraca B_BAD_TEAM_ID jeśli zmienna team nie jest prawidłowym identyfikatorem zespołu.dla działającej aplikacji. GetAppInfo() Zwraca B_ERROR jeśli aplikacja nie działa.

Struktura app_info zawiera następujące pola:

thread_id thread
   
Identyfikator dla głównego wątku wykonania aplikacji - lub 1 jeśli aplikacja nie działa. (Wątek główny jest wątkiem w którym aplikacja jest uruchomiona i w którym działa jej funkcja main().)

team_id team
   
Identyfikator dla zespołu aplikacji - lub 1 jeśli aplikacja nie działa. (To będzie ten sam zespół jak ten przekazany do GetRunningAppInfo().)

port_id port
   
Port gdzie główny wątek aplikacji odbiera komunikaty - lub 1 jeśli aplikacja nie działa.

uint32 flags
   
Pole bitowe, które zawiera informacje o zachowaniu aplikacji.

entry_ref ref
   
Referencja (odniesienie) do pliku, który był lub może być wykonany do uruchomienia aplikacji. (To będzie to samo jak parametr executable przekazany do GetAppInfo().)

char signature
   Sygnatura aplikacji. (To będzie to samo jak parametr signature przekazany do GetAppInfo().)

Pole bitowe flags może być testowane (z operatorem bitowym &) w stosunku do tych dwu stałych:

flags zawiera również wartość, która wyjaśnia zachowanie uruchamianej aplikacji. Ta wartosć jest uzyskiwana przez nałożenia maski flags ze stałą B_LAUNCH_MASK. Dla przykładu:

unit32 behavior = theInfo.flags & B_LAUNCH_MASK;

Wynik będzie pasował do jednego z tych trzech trybów:

Te tryby oddziałują na funkcję Launch() BRoster'a. Launch() może zawsze uruchamiać aplikację z trybem B_MULTIPLE_LAUNCH. Jednak nie może ona uruchamiać aplikacji z trybem B_SINGLE_LAUNCH, jeśli działająca aplikacja była już uruchomiona z tego samego pliku wykonywalnego. Nie może ona uruchamiać aplikacji z trybem B_EXCLUSIVE_LAUNCH jeśli aplikacja z tą sama sygnaturą już jest uruchomiona.

Popatrz także do: Launch(), BApplication::GetAppInfo()


GetAppList()

void GetAppList(BList *teams) const
void GetAppList(const char *signature, BList *teams) const

Wypełnia obiekt BList w parametrze teams z identyfikatorami zespołu dla aplikacji w spisie. Każda pozycja w liście będzie typu team_id. Musi być ona rzutowana na ten typ gdy jest ona uzyskiwana z tej listy, jak poniżej:

BList *teams = new BList;
be_roster->GetAppList(teams);
team_id who = (team_id)teams->ItemAt(someIndex);

Ta lista będzie zawierać jedną pozycję dla każdego egzemplarza aplikacji, która jest uruchomiona. Przykładowo, jeśli ta sama aplikacja zostałą uruchomiona trzy razy, lista będzie zawierać parametry team_id dla wszystkich trzech działających egzemplarzy aplikacji.

Jeśli jest przekazany parametr signature, lista identyfikuje tylko aplikacje działające pod tą sygnaturą. Jeśli parametr signature nie jest określony, lista identyfikuje wszystkie działające aplikacje.

Popatrz także do: TeamFor(), konstruktor BMessenger

GetRecentApps()

void GetRecentApps(BMessage *refList, int32 maxCount) const

GetRecentApps() zwraca listę większości ostatnio uruchomionych aplikacji. Parametr refList typu BMessage będzie wypełniony informacją o liczbie maxCount większości ostatnio uruchomionych aplikacji.

Wynikowy parametr refList będzie miał pole "refs", zawierające parametr entry_refs do wynikowych aplikacji.


GetRecentDocuments() patrz AddToRecentDocuments()
GetRecentFolders() patrz AddToRecentFolders()
IsRunning() patrz TeamFor()


Launch()

status_t Launch(const char *type,
      BMessage *message = NULL,
      team_id *team = NULL) const
status_t Launch(const char *type,
      BList *messages,
      team_id *team = NULL) const
status_t Launch(const char *type,
      int argc
      char **argv,
      team_id *team = NULL) const
status_t Launch(const entry_ref *file,
      const BMessage *message = NULL,
      team_id *team = NULL) const
status_t Launch(const entry_ref *file,
      const BList *messages,
      team_id *team = NULL) const
status_t Launch(const entry_ref *file,
      int argc,
      const char * const char *argv,
      team_id *team = NULL) const

ruchamia aplikację skojarzoną z typem MIME type lub z określonym plikiem file. Jeśli typ MIME type jest sygnaturą aplikacji, ta funkcja uruchamia aplikację z tą sygnaturą. W przeciwnym wypadku uruchamia ona preferowaną aplikację dla tego typu. Jeśli parametr file jest aplikacją wykonywalną, uruchamia ona tą aplikację. W przeciwnym wypadku uruchamia ona preferowaną aplikację dla tego typu i przekazuje referencję (odniesienie) file do aplikacji w komunikacie B_REFS_RECEIVED . Innymi słowy, Launch() znajduje aplikację do uruchomienia właśnie tak jak FindApp() znajduje aplikację dla konkretnego parametru type lub file.

Jeśli komunikat message jest określony będzie on wysłany do aplikacji w czasie uruchamiania gdzie będzie on odebrany i zostanie wysłana odpowiedź przed powiadomieniem aplikacji , która jest gotowa do działasnia. Podobnie, jeśli lista komunikatów messages jest określona, każdy z nich będzie dostarczony podczas uruchamiania. Wywołujący zachowuje prawa własności do obiektów BMessage (i zawartości pojemnika BList); nie będą one usuwane za Ciebie.

Wysyłanie komunikatu uruchamiania jest odpowiednie jeśli pomaga on uruchamianej aplikacji skonfigurować się zanim zacznie ona otrzymywać inne komunikaty. Aby uruchomić aplikację i wysłać jej zwyky komunikat, wywołaj Launch(), żeby zaczęła ona działać, następnie ustaw obiekt BMessenger dla tej aplikacji i wywołaj funkcję SendMessage() BMessenger'a.

Jeśli docelowa aplikacja już działa, Launch() nie uruchomi jej ponownie chyba, że pozwala ona na działanie wielu egzemplarzy jednocześnie (nie czeka ona na komunikaty aby zostały wysłane lub raporty o błędach, które wystapiły). Nie powiedzie się ona dla aplikacji z trybem B_SINGLE_LAUNCH i B_EXCLUSIVE_LAUNCH , które już zostały uruchomione. Niemniej jednak przyjmuje ona, że chcesz podać komunikat do aplikacji a więc dostarczyć go do aktualnie działąjacego egzemplarza.

Zamiast komunikatów, możesz uruchomić aplikację z tablicą argumentów łańcuchowych, które będą przekazane do jej funkcji main(). argv zawiera tablicę a argc liczbę łańcuchów. Jeśłi aplikacja akceptuje komunikaty, ta informacja będzie również zapakowana do komunikatu B_ARGV_RECEIVED, który aplikacja bedzie odbierać przy uruchamianiu.

Jeśli ta funkcja zakończy się sukcesem, Launch() umieści identyfikator niedawno uruchomionej aplikacji w zmiennej odniesionej przez parametr team i zwróci wartość równą B_OK. Jeśli nie zakończy się sukcesem, ustawi ona zmienną team na 1 i zwróci kod błędu, zwykle jeden z następujących:

Popatrz także do: klasa BMessenger, GetAppInfo(), FindApp()


StartWatching() , StopWatching()

status_t StartWatching(BMessenger target, uint32 events = B_REQUEST_LAUNCHED | B_REQUEST_QUIT) const
status_t StopWatching(BMessenger target) const

StartWatching() inicjuje monitora zdarzeń aplikacji, który jest używany do utrzymywania ścieżki zdarzeń takich jak rozpoczęcie działania aplikacji. Wywołujący określa zdarzenia do monitora poprzez argument events; target jest obiektem BMessenger do któego są wysyłąne odpowiednie komunikaty powiadamiające. Flagi events i odpowiednie komunikaty są w liście poniżej:

Flag Message
B_REQUEST_LAUNCHED B_SOME_APP_LAUNCHED
B_REQUEST_QUIT B_SOME_APP_QUIT
B_REQUEST_ACTIVATED B_SOME_APP_ACTIVATED

Pola w komunikacie powiadomienia opisują aplikację, która była uruchomiona, zamknięta lub aktywowana:

Pole Typ Opis
"mime_sig" B_STRING_TYPE sygnatura MIME
"team" B_INT32_TYPE team_id
"thread" B_INT32_TYPE thread_id
"flags" B_INT32_TYPE flagi aplikacji
"ref" B_REF_TYPE struktura entry_ref aplikacji wykonywalnej

StopWatching() kończy pracę monitora aplikacji poprzednio zainicjowanego dla danego BMessenger'a.


StartWatching()


TeamFor() , IsRunning()

team_id TeamFor(const char *signature) const
team_id TeamFor(entry_ref *executable) const
bool IsRunning(const char *signature) const
bool IsRunning(entry_ref *executable) const

Obydwie te funkcje pytają czy działa aplikacja identyfikowana przez jej sygnaturę signature lub przez referencję (odniesienie) do jej pliku wykonywalnego executable. TeamFor()StartWatching() Zwraca jej identyfikator zespołujeśłi on jest i B_ERROR jeśli go nie ma. IsRunning() zwraca wartość true jeśli ona działa i false jeśli ona nie działa.

Jeśłi aplikacja działa, prawdopodobnie będziesz chciał jej identyfikator zespołu (na przykład, do ustawienia BMessenger'a). Dlatego jest bardziej ekonomiczne po prostu wywołać TeamFor() a zrezygnować z IsRunning().

Jeśli działa więcej niż jeden egzemplarz aplikacji z sygnaturą signature lub jeśłi więcej niż jeden egzemplarz był uruchomiony z tego samego plikuwykonywalnego executable, TeamFor() sama wybiera jeden z egzemplarzy i zwraca jego identyfikator team_id.

Popatrz także do: GetAppList()


Be Book Application Kit Application Kit Indeks

Be Book,
...w ślicznym HTML...
dla BeOS wydanie 5

Copyright © 2000 Be, Inc. Wszelkie prawa zastrzeżone.