|
Pochodzi od: żaden
Zadeklarowany w: be/app/Message.h
Biblioteka: libbe.so
Alokacja: new, static lub automatic
Podsumowanie: więcej...
BMessage jest pakunkiem złożonej informacji. Każdy BMessage zawiera stałą polecenia i pewną liczbę pól danych.
- Stała polecenia jest wartością typu int32, która opisuje, z grubsza, cel BMessage. Jest ona przechowywana jako publiczna dana członkowska what. Zawsze ustawiaj i sprawdzaj wartość what bezpośrednio - nie potrzebujesz wywoływać funkcji. (Jako udogodnienie, możesz ustawić stałą polecenia, kiedy tworzysz swój obiekt BMessage.)
- Pola danych są trójkami w rodzaju nazwa-typ-wartość. Pole jest przede wszystkim identyfikowane przez nazwę, ale możesz szukać pól przez nazwę, typ albo kombinację tych dwóch. Typ jest kodowany jako stała (B_INT32_TYPE, B_STRING_TYPE, itd) i przeznaczony do opisywania typu wartości, którą przechowuje pole. Jedno pole może mieć tylko jedną nazwę i jeden typ, ale może zawierać tablicę wartości. Pojedyncze wartości w polu są dostępne przez indeks.
Ani stała dyrektywy ani pole danych nie są obowiązujące. Możesz utworzyć BMessage, który ma dane ale nie ma żadnego polecenia, albo taki który ma tylko polecenie. Jednak, tworzenie BMessage, który nie ma ani jednego ani drugiego jest bez sensu.
Obiekty BMessage są używane przez zestawy, do wysłania danych (lub powiadamiania) innych wątków - prawdopodobnie w innej aplikacji. Aby zrozumieć jak obiekty BMessage pasują do systemu komunikowania się, zobacz do"Messaging".Klasa BMessage również wnosi pewną liczbę funkcji, które pomagają definiować tworzenie skryptów systemowych. Zobacz do "Scripting" dla zaznajomienia się z tym systemem.
Obiekty BMessage są również stosowane przez pewną liczbę klas (BClipboard, BArchivable i inne) ze względu na ich zdolności, do gromadzenia danych.
Klasa BMessage definiuje pięć typów funkcji:
- Funkcje pól danych. Te funkcje albo ustawiają albo wyodrębniają wartość pola danych. Patrz do AddData(), FindData()), ReplaceData() i RemoveName().
- Funkcje informacyjne. Te funkcje wyodrębniają informacje o stanie i zawartości BMessage. Patrz do IsSystem() i GetInfo().
- Funkcje komunikacyjne. Te funkcje są częścią systemu rozgłaszania komunikatów. Mniejszy zbiór funkcji informuje o stanie otrzymanego komunikatu. Dla przykładu, IsSourceWaiting() mówi czy nadawca komunikatu czeka na odpowiedź, WasDropped() mówi czy był on (tzn. komunikat) przeciągnięty i upuszczony a DropPoint() mówi gdzie był on upuszczony. SendReply()
- Funkcje tworzenia skryptów, takie jak AddSpecifier() i PopSpecifier().
- Funkcje spłaszczające. Dane w BMessage mogą być spłaszczone. Popatrz do Flatten().
Dokumentacja dla funkcji, które przyjmują lub przekazują z powrotem obiekt BMessage powinna Ci powiedzieć, kto jest odpowiedzialny za usuwanie obiektu. Większość funkcji, które przyjmują argument BMessage kopiująten obiekt, pozostawiając na wywołującym odpowiedzialność za usunięcie tego argumentu. Wyjątki - tj. funkcje przyjmujące BMessage, które przejmują obiekt na własność - są wymienione poniżej:Funkcje, które zwracają Ci BMessage zwykle nie rezygnują z jego posiadania; na ogół nie usuwasz obiektów BMessage, które przekazywane są do Ciebie. Wyjątki - funkcje, które oczekują by wywołujący przejął na własność BMessage - są opisane poniżej:
uint32 what
Kodowana stała, która wychwytuje informację o tym czym jest komunikat.
![]() | BMessage() |
BMessage(uint32 command)
BMessage(const BMessage &message)
BMessage(void)Tworzy nowy obiekt BMessage który ma daną stałą polecenia command lub który jest kopią innego BMessage'a. Jeśli jest on kopią,nowy obiekt zawiera tą samą stałą polecenia i pola danych jako komunikat message.
Popatrz także do: BLooper::DetachCurrentMessage()
![]() | ~BMessage() |
virtual ~BMessage() Zwalnia całą pamięć przydzieloną do przechowywania danych komunikatu. Jeśli nadawca komunikatu spodziewa się odpowiedzi lecz go jeszcze nie otrzymał wysyłana jest odpowiedź domyślna (z B_NO_REPLY jako daną członkowską what) przed zniszczeniem komunikatu.
System zachowuje na własność komunikat, który Ci dostarcza. Każda pętla komunikatu obsługuje usuwanie dostarczonych obiektów BMessage, po tym jak aplikacja zakończy odpowiadanie na nie (tj. te komunikaty).
status_t AddData(const char *name, type_code type,
const void *data,
ssize_t numBytes,
bool fixedSize = true,
int32 numItems = 1)status_t AddBool(const char *name, bool aBool) status_t AddInt8(const char *name, int8 anInt8) status_t AddInt16(const char *name, int16 anInt16) status_t AddInt32(const char *name, int32 anInt32) status_t AddInt64(const char *name, int64 anInt64) status_t AddFloat(const char *name, float aFloat) status_t AddDouble(const char *name, double aDouble) status_t AddString(const char *name, const char *string)
status_t AddString(const char *name, const BString &string)status_t AddPoint(const char *name, BPoint point) status_t AddRect(const char *name, BRect rect) status_t AddRef(const char *name, const entry_ref *ref) status_t AddMessage(const char *name, const BMessage *message) status_t AddMessenger(const char *name, BMessenger messenger) status_t AddPointer(const char *name, const void *pointer) status_t AddFlat(const char *name, BFlattenable *object, int32 numItems = 1) Te funkcje dodają dane do pola nazywanego name i przypisują typ danych do pola. Nazwy pól nie mogą mieć długości większej niż 255 znaków. Jeśli jest dodany więcej niż jeden element danych pod tą samą nazwą, BMessage tworzy tablicę danych dla tej nazwy. Za każdym razem gdy dodajesz kolejną wartość (do tej samej nazwy), wartość jest dodawana na koniec tablicy - nie możesz dodawać wartości z określonym indeksem. Dane pole może przechowywać tylko jeden typ danych.
AddData() kopiuje liczbę numBytes bajtów z danej data do pola i przypisuje danej kod typu type. Kopiuje ona jakiekolwiek dane na jakie wskazuje wskaźnik data. Dla przykładu, jeśli chcesz dodać łańcuch znaków do komunikatu, data powinno być wskaźnikiem wskazującym na typ string (char *). Jeśli chcesz dodać tylko wskaźnik do danych typu string a nie same znaki, data powinno być wskaźnikiem do wskaźnika (char **). Przypisany typ type musi być daną określonego typu; nie powinien on być B_ANY_TYPE.
Kiedy wywołujesz AddData() aby umieścić pierwszy element w tablicy pod nową nazwą, możesz dostarczyć go z dwoma argumentami, fixedSize i numItems, które będą poprawiać wydajność obiektu. Jeśli flaga fixedSize jest ustawiona na true, każdy element w tablicy musi mieć taką samą liczbę bajtów; jeśli flaga jest ustawiona na false, elementy mogą mieć różny rozmiar. numItems mówi obiektowi aby wstępnie przydzielił pamięć dla pewnej liczby elementów. Nie jest ono ograniczeniem - możesz dodać więcej niż numItems do tego pola.
Większość innych funkcji jest wariantem AddData(),który na sztywno koduje typ pola danych. Dla przykładu, AddFloat() przypisuje typ B_FLOAT_TYPE; AddBool() przypisuje B_BOOL_TYPE, i tak dalej.
AddString(), tak jak AddData(), pobiera wskaźnik do tych dodanych danych albo możesz użyć obiektu BString. string musi być łńcyuchem znaków zakończonym ogranicznikiem zerowym; znak zera jest zliczany i kopiowany do komunikatu. Podobnie, AddRef() dodaje wskazanie na strukturę entry_ref do komunikatu (i nazwę o zmiennej długości, która jest jednym z elementów struktury); AddMessage() dodaje jeden BMessage do innego.
Inne funkcje służą po prostu do przekazywania danych bezpośrednio. Dla przykładu, AddInt32() pobiera daną typu int32 lub uint32 a AddMessenger() pobiera obiekt BMessenger, podczas gdy AddData() będzie przekazywać wskaźnik do int32 i wskaźnik do BMessenger. AddPointer() dodaje tylko przekazywany wskaźnik a nie dane na które on wskazuje. Aby dokonać tego samego, AddData() będzie pobierać wskaźnik do wskaźnika. (Wskaźnik będzie sprawdzany tylko lokalnie; nie będzie on użyteczny dla zdalnego miejsca przeznaczenia (adresu).)
AddFlat() spłaszcza obiekt oznaczony jako object (przez wywołanie jego funkcji Flatten()) i dodaje spłaszczone dane do komunikatu. Wywołuje ona funkcję TypeCode() obiektu aby poznać kod typu, który powinna ona skojarzyć z danymi. Obiekty które są dodawane poprzez AddFlat() muszą dziedziczyć z BFlattenable (zdefiniowany w Support Kit).
Możesz również odstarczyć wskazówkę numItems do AddFlat() gdy wywołujesz ją aby ustanowić nową tablicę. AddFlat() wywołuje funkcję IsFixedSize() obiektu aby dowiedzieć się czy wszystkie elementy w tablicy będą tego samego rozmiaru.
Te funkcje zwracają wartość B_ERROR jeśli dane są zbyt duży rozmiar aby zostały dodane do komunikatu, B_BAD_TYPE jeśli dane nie mogą być dodane do istniejącej tablicy ponieważ mają one niewłaściwy typ, B_NO_MEMORY jeśli BMessage nie może dostać więcej pamięci do przechowywania danych i B_BAD_VALUE jeśli proponowana nazwa name dla danych jest dłuższa niż 255 bajtów. Jeśli wszystko przebiegło dobrze wtedy zwracają one B_OK.
Nie ma ograniczenia co do liczby nazwanych pól któe komunikat może zawierać lub rozmiaru pól danych. Jednakże, ponieważ przeszukiwanie jest liniowe może być ono mało wydajne, przy przeszukiwaniu bardzo długiej listy nazw, by znaleźć konkretny fragment danych. Również z powodu ilości danych, które muszą być przemieszczone, niezmiernie duży komunikat może spowolnić mechanizm przekazywania. Czasami jest lepiej umieścić część informacji w wspólnym miejscu (plik, prywatny schowek, współdzielony obszar pamięci) i tylko odnieść się do niego w komunikacie.
Popatrz także do: FindData(), GetInfo()
![]() | AddSpecifier() |
status_t AddSpecifier(const BMessage *message)
status_t AddSpecifier(const char *property)
status_t AddSpecifier(const char *property, int32 index)
status_t AddSpecifier(const char *property, int32 index, int32 range)
status_t AddSpecifier(const char *property, const char *name)Dodaje specyfikator do stosu specyfikatora. Jest kilka odman tej metody. Pierwsza dodaje specyfikator komunikatu message do stosu specyfikatora. Inna metoda dodaje specyfikator docelowej właściwości property, ze stałymi specyfikatora odpowiednio: B_DIRECT_SPECIFIER, B_INDEX_SPECIFIER, B_RANGE_SPECIFIER, i B_NAME_SPECIFIER. Dla wszystkich innych specyfikatorów musisz oddzielnie skonstruować specyfikator i wywołać wtedy na komunikacie AddSpecifier(). Aby zdobyć więcej informacji o specyfikatorach, popatrz do sekcji "Scripting" blisko początku tego rozdziału.
Specyfikatory są przechowywane w tablicy danych nazwanej "specifiers" (czyli specyfikatory). Jednak ponieważ AddSpecifier() ustanawia również pojęcie bieżącego specyfikatora, specyfikatory powinny być zawsze dodawane do komunikatu skryptowego z tą metodą a nie z AddMessage().
AddSpecifier() zwraca wartość równą B_OK jeśli była zdolna dodać specyfikator do BMessage a jeśli nie była zdolna zwraca kod błędu, ale tylko ogólny o wartości B_NO_MEMORY aby pokazać, że nie ma pamięci aby mogła zadziałać.
Popatrz także do: GetCurrentSpecifier(), HasSpecifiers(), PopSpecifier()
![]() | CountNames() |
int32 CountNames(type_code type) const Zwraca liczbę nazwanych pól danych w BMessage, które przechowują dane określone jako type. Tablica informacji jest utrzymywana pod pojedynczą nazwą oznaczoną jako jedno pole; każda nazwa jest zliczana tylko raz, bez względu na to jak wiele elementów danych jest przechowywanych pod tą nazwą.
Jeśli type jest równe B_ANY_TYPE, ta funkcja zlicza wszystkie nazwane pola. Jeśli type jest określonym typem, zlicza ona tylko te pola, które przechowują dane zarejestrowane jako ten typ.
Popatrz także do: GetInfo()
![]() | DropPoint() patrz WasDropped() |
status_t FindData(const char *name,
type_code type,
int32 index,
const void **data,
ssize_t *numBytes) const
status_t FindData(const char *name,
type_code type,
const void **data,
ssize_t *numBytes) conststatus_t FindBool(const char *name,
int32 index,
bool *aBool) const
status_t FindBool(const char *name, bool *aBool) conststatus_t FindInt8(const char *name,
int32 index,
int8 *anInt8) const
status_t FindInt8(const char *name,
int8 *anInt8) conststatus_t FindInt16(const char *name,
int32 index,
int16 *anInt16) const
status_t FindInt16(const char *name, int16 *anInt16) conststatus_t FindInt32(const char *name,
int32 index,
int32 *anInt32) const
status_t FindInt32(const char *name, int32 *anInt32) conststatus_t FindInt64(const char *name,
int32 index,
int64 *anInt64) const
status_t FindInt64(const char *name, int64 *anInt64) conststatus_t FindFloat(const char *name,
int32 index,
float *aFloat) const
status_t FindFloat(const char *name, float *aFloat) conststatus_t FindDouble(const char *name,
int32 index,
double *aDouble) const
status_t FindDouble(const char *name, double *aDouble) conststatus_t FindString(const char *name,
int32 index,
const char **string) const
status_t FindString(const char *name, const char **string) const
status_t FindString(const char *name, BString *string) const
status_t FindString(const char *name, int32 index, BString *string) conststatus_t FindPoint(const char *name,
int32 index,
BPoint *point) const
status_t FindPoint(const char *name, BPoint *point) conststatus_t FindRect(const char *name,
int32 index,
BRect *rect) const
status_t FindRect(const char *name, BRect *rect) conststatus_t FindRef(const char *name,
int32 index,
entry_ref *ref) const
status_t FindRef(const char *name, entry_ref *ref) conststatus_t FindMessage(const char *name,
int32 index,
BMessage *message) const
status_t FindMessage(const char *name, BMessage *message) conststatus_t FindMessenger(const char *name,
int32 index,
BMessenger *messenger) const
status_t FindMessenger(const char *name, BMessenger *messenger) conststatus_t FindPointer(const char *name,
int32 index,
void **pointer) const
status_t FindPointer(const char *name, void **pointer) conststatus_t FindFlat(const char *name,
int32 index,
BFlattenable *object) const
status_t FindFlat(const char *name, BFlattenable *object) constTe funkcje wyodrębniają dane z BMessage. Każda szuka danych przeszukiwanych pod określoną nazwą name. Jeśli więcej niż jeden element danych ma tą amą nazwę, można dostarczyć indeks index aby powiedzić funkcji który element powinna ona szukać w tablicy name. Indeksy zaczynają się od 0. Jeśli indeks nie jest dostarczony, funkcja będzie szukać tylko pierwszy element w tablicy.
![]()
We wszystkich przypadkach za wyjątkiem FindData() i FindString(), dane które są wyodrębniane z BMessage są kopiowane do argumentu odniesienia; wywołujący jest odpowiedzialny za zwolnienie skopiowanych danych. Dla FindData() i nie posługującej się obiektem BString wesji funkcji FindString(), zwracany jest wskaźnik do danych; BMessage zatrzymuje na własność rzeczywiste dane i zniszczy dane gdy ten obiekt usunie sam siebie.
FindData() umieszcza, w *data, wskaźnik do żądanego elementu danych. Rozmiar elementu w bajtach jest zapisywany do numBytes. Jeśli type ma wartość równą B_ANY_TYPE, dostarcza on wskaźnik do danych bez względu na to jaki jest faktyczny typ. Ale jeśli type jest daną określonego typu, dostarcza on wskaźnik tylko jeśli pole name przechowuje dane tego szczególnego typu.
Inne funkcje są wyspecjalizowanymi wersjami funkcji FindData(). Zestawiają one odpowiednie funkcje Add...() i szukają nazwanych danych konkretnego typu jak opisano to poniżej:
Funkcja Znajduje dane Zarejestrowany jako typ FindBool() bool B_BOOL_TYPE FindInt8() int8 lub uint8 B_INT8_TYPE FindInt16() int16 lub uint16 B_INT16_TYPE FindInt32() int32 lub uint32 B_INT32_TYPE FindInt64() int64 lub uint64 B_INT64_TYPE FindFloat() float B_FLOAT_TYPE FindDouble) double B_DOUBLE_TYPE FindString() łańcuch znaków B_STRING_TYPE FindPoint() obiekt BPoint B_POINT_TYPE FindRect() obiekt BRect B_RECT_TYPE FindRef() entry_ref B_REF_TYPE FindMessage() obiekt BMessage B_MESSAGE_TYPE FindMessenger() obiekt BMessenger B_MESSENGER_TYPE FindPointer() wskaźnik do wszystkiego B_POINTER_TYPE Inne funkcje dla określonych typów wydobywają żądane element danych z komunikatu przez skopiowanie go do zmiennej do której można się odnieść przez ostatni argument; moszesz uzyskać dane ale nie wskaźnik do nich. Dla przykładu, FindMessenger() przypisuje BMessenger znaleziony przez nią w komunikacie do obiektu messenger, podczas gdy FindData() dostarczy tylko wskaźnik BMessenger'a. FindPointer() umieści znaleziony wskaźnik w zmiennej typu void* do której odnosi się wskaźnik pointer; FindData(), jak pokazano wyżej, dostarczy wskaźnik do wskaźnika. (Jeśli komunikat był dostarczony ze źródła zdalnego, wskaźniki wydobyte z komunikatu nie będa ważne.)
FindRef() wydobywa strukturę entry_ref; dane które są używane do ponownego złożenia struktury mogą być dodane jako entry_ref (poprzez AddRef()) lub jako spłaszczony obiekt BPath (AddFlat()).
FindFlat() przypisuje obiekt przechowywany w BMessage do obiektu object przekazywanego jako argument - wywołuje ona funkcję Unflatten() obiektu object i przekazuje jej spłaszczone dane z komunikatu - pod warunkiem że te dwa obiekty mają zgodne typy. Funkcja AllowsTypeCode() argumentu object musi zwrócić wartość true gdy jest sprawdzany z kodem typu w komunikacie; jeśli nie, FindFlat() nie zadziała i zwróci wartość B_BAD_VALUE.
Jeśli te funkcje nie mogą znaleźć żdnych danych przypisanych do argumentu name, wtedy zwracają one błąd B_NAME_NOT_FOUND. Jeśli nie mogą one znaleźć danej name żądanego typu type (lub zwracanego typu funkcji), wtedy zwracają wartość równą B_BAD_TYPE. Jeśli argument index jest spoza zakresu, wtedy zwracają wartość równą B_BAD_INDEX. Możesz polegać na wartościach które one zwracają tylko jeśli te wartości są równe B_OK a dane były prawidłowo zapisane gdy były dodawane do komunilkatu.
Gdy nie zadziałają, FindData() i FindString() dostarczają wskaźniki równe NULL. FindRect() da Ci nieprawidłowy prostokąt a FindMessenger() nieprawidłowy BMessenger. Większość innych funkcji ustawi wartości danych na 0, które mogą być nie do odróżnienia od prawidłowych wartości.
Znalezienie danych nie usuwa ich z BMessage.
(Niektóre funkcje takie jak FindRect() i FindInt32(), mają wersja które zwracają znalezione wartości bezpośrednio. Te wersje nie zgłaszają błędów i mogą nie być wspierane w przyszłości.)
Popatrz także do: GetInfo(), AddData()
![]() | Flatten() , Unflatten() , FlattenedSize() |
status_t Flatten(BDataIO *object, ssize_t *numBytes = NULL) const
status_t Flatten(char *address, ssize_t numBytes = NULL) conststatus_t Unflatten(BDataIO *object)
status_t Unflatten(const char *address)ssize_t FlattenedSize(void) const Te funkcje zapisują BMessage i dane które on zawiera do "płaskiego" (untyped - bez określonego typu) bufora bajtów i rekonstruują obiekt z takiego bufora.
Jeśli przekazano obiekt object typu BDataIO (w tym BFile), funkcja Flatten() wywołuje funkcję Write() obiektu do zapisania danych komunikatu. Jeśli przekazano adres address bufora, rozpocznie ona zapisywanie bufora od początku. FlattenedSize() zwraca liczbę bajtów którą musisz dostarczyć w buforze (czyli konieczny rozmiar bufora - przyp. tłum.) do umieszczenia spłaszczonego obiektu. Flatten() umieszcza liczbę bajtów rzeczywiście zapisaną w zmiennej, do której odnosi się argument numBytes.
Unflatten() opróżnia BMessage z informacji, która mogła być tam zawarta a nastęnie inicjalizuje obiekt z danych odczytanych z buforu. Jeśli przekazano obiekt object typu BDataIO wywołuje ona funkcję Read() obiektu aby odczytać dane komunikatu. Jeśi przekazano adres address buforu, rozpoczyna ona odczytywanie bufora od początku. Od wywołującego zależy upewnienie się, że funkcja Unflatten() czyta dane, które zapisała funkcja Flatten() i że wskaźniki są umieszczone prawidłowo.
Flatten() zwraca błędy napotkane podczas zapisywania danych lub B_OK jeśli nie było błędów.
Jeśli nie może ona rozpoznać danych w buforze jako istniejący spłaszczony obiekt lub gdy nie powiedzie się czytanie danych, Unflatten() zwraca wartość B_BAD_VALUE. Jeśli nie ma odpowidniej pamięci do odtworzenia całego komunikatu, zwraca ona B_NO_MEMORY. W przeciwnym wypadku zwraca wartość równą B_OK.
Popatrz także do: klasa BDataIO w Support Kit.
![]() | GetCurrentSpecifier() , PopSpecifier() |
status_t GetCurrentSpecifier(int32 *index,
BMessage *specifier = NULL,
int32 *what = NULL,
const char **property = NULL) conststatus_t PopSpecifier(void) GetCurrentSpecifier() rozpakowuje bieżący specyfikator w BMessage, ten z wierzchołka stosu specyfikatora; PopSpecifier() zmienia zamiar tego specyfikatora, który jest bieżący, przez zdjęcie go ze stosu.
Te funkcje pomagają w implementowaniu zależnej od klasy funkcji ResolveSpecifier() obiektu BHandler - najpierw otrzymuje specyfikator, który potrzebuje do podjęcia decyzji a po tym jak już zdecyduje zdejmuje drugi ze stosu. Możesz również wywołać je do sprawdzenia odnośnego specyfikatora kiedy obsługujesz komunikaty które są zaadrresowane własnością obiektu (taki jak B_GET_PROPERTY).
BMessage skryptowy przechowuje specyfikatory w tablicy danych nazwanej "specifiers" (specyfikatory); każdy specyfikator jest samym obiektem BMessage, ale ale jeden ze specjalną strukturą i celem w systemie skryptowym. Popatrz do sekcji "Scripting" blisko początku tego rozdziału aby przeglądnąć system i miejsce specyfikatów w systemie.
Specyfikatory w komunikacie są uszeregowane i dopóki jest wywołana funkcja PopSpecifier(), ten który był dodany ostatni - ten z najwyższym indeksem - jest bieżącym specyfikatorem. PopSpecifier() tylko zmniejsza indeks, który wybiera bieżący element, nie usuwa ona niczego z BMessage.
GetCurrentSpecifier() wstawia indeks bieżącego specyfikatora do zmiennej do której odnosi się jej pierwszy argument index. Jeśli są dostarczone inne argumenty to tworzy ona kopię bieżącego specyfikatora argumentowi specifier obiektu BMessage. Wydobywa ona również dwa fragmenty informacji ze specyfikatora specifier: Umieszcza ona daną członkowską what specyfikatora w zmiennej what i wskaźnik do nazwy właściwości w zmiennej property. Te dwa ostatnie argumenty nie będą ważne jeżeli argument specifier jest równy NULL.
Obie funkcje nie zadziałają jeżeli BMessage nie zawiera specyfikatorów. Dodatkowo, GetCurrentSpecifier() nie zadziała jeśli nie znajdzie w obiekcie BMessage danych do swoich argumentów specifier i property a PopSpecifier() nie zadziała jeśli BMessage nie jest tym, który został Ci dostarczony po przetworzeniu poprzez pętlę komunikatów. Gdy nie zadziałaąją, GetCurrentSpecifier() zwróci B_BAD_SCRIPT_SYNTAX ale PopSpecifier() zwróci B_BAD_VALUE. Jeżeli zakończą się sukcesem obie funkcje zwracają wartość B_OK.
Popatrz także do: AddSpecifier(), HasSpecifiers(), BHandler::ResolveSpecifier()
![]() | GetInfo() |
status_t GetInfo(const char *name,
type_code *typeFound,
int32 *countFound = NULL) const
status_t GetInfo(const char *name,
type_code *typeFound,
bool *fixedSize) const
status_t GetInfo(type_code type, int32 index,
char **nameFound,
type_code *typeFound,
int32 *countFound = NULL) constDostarcza informacji o polach danych przechowywanych w BMessage.
Kiedy zostaje przekazany argument name którego treść pasuje do nazwy w BMessage, funkcja GetInfo() umieszcza kod typu dla danych przechowywanych pod tą nazwą w zmiennej przekazywanej przez typeFound i zapisującej liczbę elementów danych z tą nazwą w zmiennej przekazwyanej przez countFound. Zwraca ona wtedy B_OK. Jeśli nie może ona znaleźć nazwy pola name wewnątrz BMessage, to ustawia zmienną countFound na 0, i zwraca B_NAME_NOT_FOUND (bez modyfikowania zmiennej typeFound).
Kiedy argument fixedSize jest określony, wartość typu bool przekazywana przez fixedSize jest ustawiana na true jeśli wszystkie elementy w tablicy określonej przez nazwę muszą być tego samego rozmiaru i false jeśli elementy mogą być różnych rozmiarów (patrz do AddData()).
Kiedy zostają przekazane argumenty type i index, funkcja GetInfo() przegląda tylko te pola, które przechowują dane żądanego typu i dostarcza informacji o polu z żadanym indeksem. Indeksy rozpoczynają się od 0 i są określonego typu. Dla przykładu, jeśli żądany typtype jest równy B_DOUBLE_TYPE a BMessage zawiera całość trzech nazwanych pól, które przechowują dane double, pierwsze pole będzie opatrzone indeksem index 0, drugie 1 a trzecie 2 - obojętnie jakie inne typy danych aktualnie rozdzielających je w BMessage i obojętnie jak wiele elementów danych każde pole zawiera. (Zauważ, że indeks w tym przypadku sięga ponad pola, każde z inną nazwą, nie ponad elementy danych wewnątrz konkretnie nazwanego pola.) Jeśli żądany typ jest równy B_ANY_TYPE, ta funkcja przegląda wszystkie pola i przekazuje informacje o jednym polu z indeksem index jakiegokolwiek typu ono jest.
Jeśli zakończy się sukcesem szukając danych type o żadanym indkesie index, GetInfo() zwróci B_OK i dostarczy informacji o danych poprzez ostatni z trzech argumentów:
- Umieszcza wskaźnik do nazwy pola danych w zmiennej przekazywanej przez nameFound.
- Wstawia kod dla typu danych pola zawartego w zmiennej przekazywanej przez typeFound. Będzie to tak sam jak żadany typ type, chyba, że żądany typ jest równy B_ANY_TYPE, w tym przypadku typeFound będzie typem rzeczywiście przechowywanym pod tą nazwą.
- Wpisuje liczbę elementów danych przechowywanych wewnątrz pola w zmiennej przekazywanej przez countFound.
Jeśli GetInfo() niemoże znaleźć danych żądanego typu type o indeksie index, ustawia ona zmienną countFound na 0 i zwraca wartość równą B_BAD_TYPE. Jeśli indeks jest spoza zakresu zwraca ona wartość B_BAD_INDEX.
Ta wersja GetInfo() może być używana do przeglądania wszystkich danych BMessage'a. Dla przykładu:
char *name;
uint32 type;
int32 count;
for ( int32 i = 0;
msg->GetInfo(B_ANY_TYPE, i, &name, &type, &count) == B_OK;
i++ ) {
. . .
}Jeśli indeks jest zwiększany od 0 taki sposób, to wszystkie dane żądanego typu będą mogły być odczytane gdy GetInfo() zwróci wartość równą B_NAME_NOT_FOUND. Jeśli żądany typ jest równy B_ANY_TYPE, jak pokazano powyżej, będzie ona odsłaniać nazwę i typ każdego pola w BMessage.
Popatrz także do: HasData(), AddData(), FindData()
![]() | HasSpecifiers() |
bool HasSpecifiers(void) const Zwraca true jeśli BMessage ma specyfikatory dodane przez funkcję AddSpecifier() i false jeśli nie ma.
Popatrz także do: AddSpecifier(), GetCurrentSpecifier()
![]() | IsEmpty() patrz MakeEmpty() |
![]() | IsReply() patrz WasDelivered() |
![]() | IsSourceRemote() patrz WasDelivered() |
![]() | IsSourceWaiting() patrz WasDelivered() |
![]() | IsSystem() |
bool IsSystem(void) const Zwraca true jeśli dana członkowska what obiektu BMessage określa go jako komunikat zdefiniowany przez system i false jeśli nie jest zdefiniowany przez system.
![]() | MakeEmpty() , IsEmpty() |
status_t MakeEmpty(void) bool IsEmpty(void) const MakeEmpty() usuwa i zwalnia wszystkie dane które zostały dodane do BMessage, bez zmieniania stałej what. Zwraca ona wartość równą B_OK, chyba, że komunikat nie mógł być zmieniony (nie może wtedy, jeżeli jest on komunikatem przeciąganym), w takim przypadku zwraca ona wartość równą B_ERROR.
IsEmpty() zwraca true jeśli BMessage nie ma danych (czy mógł być opróżniony przez MakeEmpty() czy nie mógł) i false jeśli ma jakieś dane.
Popatrz także do: RemoveName()
![]() | Previous() patrz WasDelivered() |
![]() | PrintToStream() |
void PrintToStream(void) const Drukuje informacje o BMessage do standardowego strumienia wyjściowego (stdout). Każde pole nazwanych danych jest przedstawiane w następującym formacie,
#entry name, type = type, count = count
gdzie name jest nazwą pod którą są zarejestrowane te dane, type jest stałą która wskazuje jaki to jest typ danych a count jest liczbą elementów danych w nazwanej tablicy.
![]() | RemoveName() , RemoveData() |
status_t RemoveName(const char *name) status_t RemoveData(const char *name, int32 index = 0) RemoveName() usuwa wszystkie dane wprowadzone w BMessage'u pod nazwą name i samą nazwę. RemoveData() usuwa pojedynczy element danych o indeksie index w tablicy name. Jeśli tablica ma tylko jeden element danych, to ta funkcja usuwa tablicę i nazwę tak samo jak zrobiłaby to funkcja RemoveName().
Obie funkcje zwalniają pamięć która była zarezerwowana (zaalokowana) do przechowywania tych danych i zwracają wartość równą B_OK gdy zakończą się sukcesem. Jednak, jeśli nie ma danych w BMessage'u pod nazwą name, wtedy zwracają błąd B_NAME_NOT_FOUND. Jeśli dane komunikatu mogą być czytane ale nie mogą być zmieniane (jak może to się zdarzać dla komunikatu, który powstał jako przeciągany), wtedy obie zwracają wartość równą B_ERROR. Jeśli indeks index jest spoza zakresu, RemoveData() zwraca B_BAD_INDEX (indeks jest za wysoki) lub B_BAD_VALUE (przekazana wartość jest liczbą ujemną).
Popatrz także do: MakeEmpty()
status_t ReplaceData(const char *name,
type_code type,
const void *data,
ssize_t numBytes)
status_t ReplaceData(const char *name,
type_code type,
int32 index,
const void *data,
ssize_t numBytes)status_t ReplaceBool(const char *name, bool aBool)
status_t ReplaceBool(const char *name,
int32 index,
bool aBool)status_t ReplaceInt8(const char *name, int8 anInt8)
status_t ReplaceInt8(const char *name,
int32 index,
int8 anInt8)status_t ReplaceInt16(const char *name, int16 anInt16)
status_t ReplaceInt16(const char *name,
int32 index,
int16 anInt16)status_t ReplaceInt32(const char *name, long anInt32)
status_t ReplaceInt32(const char *name,
int32 index,
int32 anInt32)status_t ReplaceInt64(const char *name, int64 anInt64)
status_t ReplaceInt64(const char *name,
int32 index,
int64 anInt64)status_t ReplaceFloat(const char *name, float aFloat)
status_t ReplaceFloat(const char *name,
int32 index,
float aFloat)status_t ReplaceDouble(const char *name, double aDouble)
status_t ReplaceDouble(const char *name,
int32 index,
double aDouble)status_t ReplaceString(const char *name, const char *string)
status_t ReplaceString(const char *name,
int32 index,
const char *string)status_t FindString(const char *name, BString &string)
status_t FindString(const char *name, int32 index, BString &string)status_t ReplacePoint(const char *name, BPoint point)
status_t ReplacePoint(const char *name,
int32 index,
BPoint point)status_t ReplaceRect(const char *name, BRect rect)
status_t ReplaceRect(const char *name,
int32 index,
BRect rect)status_t ReplaceRef(const char *name, entry_ref *ref)
status_t ReplaceRef(const char *name,
int32 index,
entry_ref *ref)status_t ReplaceMessage(const char *name, BMessage *message)
status_t ReplaceMessage(const char *name,
int32 index,
BMessage *message)status_t ReplaceMessenger(const char *name, BMessenger messenger)
status_t ReplaceMessenger(const char *name,
int32 index,
BMessenger messenger)status_t ReplacePointer(const char *name, const void *pointer)
status_t ReplacePointer(const char *name,
int32 index,
const void *pointer)status_t ReplaceFlat(const char *name, BFlattenable *object)
status_t ReplaceFlat(const char *name,
int32 index,
BFlattenable *object)Te funkcje zastępują element danych w polu name innym elementem przekazanym jako argument. Jeśli jest dostarczony indeks index, zastępują one element o tym indeksie w tablicy name; jeśli indeks index nie jest wymieniony, wtedy zastępują one pierwszy (lub tylko pierwszy) element przechowywany pod nazwą name. Jeśli inkdeks index jest dostarczony ale jest spoza zakresu, zastępowanie nie zachodzi.
ReplaceData() zastępuje element w polu name z argumentem numBytes danych data, ale tylko wtedy jeśli kod typu type który jest określony dla danych pasujących do typu danych, który jest już przechowywany w polu. Typ type musi być określony; nie może on być B_ANY_TYPE.
ReplaceFlat() zastępuje spłaszczony (flattened) obiect innym obiektem object, dostarczonym tak, że typ przedstawiony przez argument object (przez jego funkcję TypeCode()) pasuje do typu zapisanego do elementu w komunikacie. Jeśli nie zastąpi to zwraca wartość równą B_BAD_VALUE.
Inne funkcje są uproszczonymi wersjami ReplaceData(). Każda z nich obsługuje określony typ danych zadeklarowany dla jej ostatnich argumentów. Kończą działanie z sukcesem jeśli ten typ pasuje do typu danych już obecnych w polu name a kończą się niepowodzeniem gdy te typy nie są zgodne. Nowe dane są dodawane dokładnie jak dodałby je odpowiednik funkcji Add...().
Jeśli zakończą się one sukcesem, wszyskie funkcje zwracają wartość równą B_OK. Jeśli nie zakończą się sukcesem , zwracają kod błędu - B_ERROR jeśli komunikat jest tylko do odczytu (jest tak kiedy komunikat powstał jako przeciągany), B_BAD_INDEX jeśli indeks index jest spoza zakresu, B_NAME_NOT_FOUND jeśli pole name nie istnieje lub B_BAD_TYPE jeśli pole nie zawiera danych określonego typu.
Popatrz także do: AddData()
![]() | ReturnAddress() |
BMessenger ReturnAddress(void) Zwraca obiekt BMessenger który może być użyty do przekazania odpowiedzi na BMessage. Wywołanie funkcji SendMessage() obiektu BMessenger zastęuje wywołanie SendReply(), z tym wyjątkiem, że zwracany komunikat nie będzie oznaczony jako odpowiedź. Jeśli odpowiedź nie jest uznana (jeśli BMessage nie był dostarczony), zwracany obiekt BMessenger będzie nieprawidłowy.
Jeśli chcesz użyć ReturnAddress() BMessenger'a aby wysłać odpowiedź synchroniczną, musisz zrobić to zanim BMessage zostanie usunięty i zanim zostanie wysłany komunikat domyślny.
Popatrz także do: SendReply(), WasDelivered()
![]() | SendReply() |
status_t SendReply(BMessage *message,
BMessage *reply,
bigtime_t sendTimeout = B_INFINITE_TIMEOUT,
bigtime_t replyTimeout = B_INFINITE_TIMEOUT)
status_t SendReply(BMessage *message,
BHandler *replyHandler = NULL,
bigtime_t sendTimeout = B_INFINITE_TIMEOUT)
status_t SendReply(uint32 command, BMessage *reply)
status_t SendReply(uint32 command, BHandler *replyHandler = NULL)Wysyła zwrotny komunikat odpowiedzi message do nadawcy BMessage'a (w przypadku odpowiedzi synchronicznej) lub do BHandler'a adresata (w przypadku odpowiedzi asynchronicznej). Czy odpowiedź jest synchroniczna czy asynchroniczna zależy to od tego jak BMessage, który jest wysyłany jako odpowiedź sam był wysłany:
- Odpowiedź jest dostarczona synchronicznie jeśli komunikat nadawcy czeka na jej przybycie. Odpowiedź jest dostarczona synchronicznie, jeśli nadawca komunikatu czeka na jego przybycie. Funkcja, która wysłała BMessage nie zwraca swojejwartości, dopóki nie ona odbierze odpowiedzi (lub upłynie przerwa). Jeśli oczekiwana odpowiedź nie została wysłana przez ten czas obiekt BMessagejest usuwany, a do nadawcy jest zwracany domyślny komunikat B_NO_REPLY.Jeśli odpowiedź jest wysłana, po tym jak nadawca zrezygnował z czekania na jej przybycie, komunikat odpowiedzi message znika we wnętrzu systemu.
- Odpowiedź jest dostarczana asynchronicznie, jeśli nadawca komunikatu nie czeka na odpowiedź. W tym przypadku, funkcja wysyłająca wyznacza docelowy BHandler i BLooper dla jakichkolwiek odpowiedzi, które mogą zostać wysłane a następnie natychmiast zwraca wartość po umieszczeniu BMessage'a w kolejce. Komunikaty wysłane i te które są przeciągane i upuszczane, również nadają się dla odpowiedzi asynchronicznych.
SendReply() działa tylko dla obiektów BMessage, które zostały przetworzone przez pętlę komunikatu i dostarczone do Ciebie. Wywołujący zachowuje prawo własności do komunikatu odpowiedzi message przekazanego do SendReply(); może on zostać usunięty (lub pozostawiony, by umrzeć na stosie) po powrocie funkcji.
SendReply() wysyła komunikat - komunikat odpowiedzi , jest pewny, ale niemniej jednak to komunikat. Zachowuje się ona dokładnie taki samo jak inna funkcja przesyłająca komunikat, SendMessage() BMessenger'a:
- Przez przekazanie jej argumentu reply , możesz zapytać o odpowedź asynchroniczną na ten wysłany komunikat odpowiedzi you can ask for a synchronous reply to the reply message it sends. Nie zwróci ona wartości dopóki nie odbierze odpowiedzi.
- Przez dostarczenie argumentu replyHandler , możesz przygotować się na oczekiwaną odpowiedź asynchroniczną. Jeśli określony adresat nie jest wyszczególniony, obiekt BApplication będzie obsługiwał odpowedź jeśli jest ona wysłana.
Domyślnie, SendReply() nie zwraca wartości dopóki komunikat odpowiedzi jest dostarczony (umieszczony w orcie kolejki BLooper'a). Jest to możliwe, w niektórych wypadkach, dla odbierającego portu kolejki, aby był pełny, w tym przypadku SendReply() będzie blokowana, aż gniazdo zostanie opróżnione. Jednak, możesz ograniczyć czas jak długo SendReply() będzie czekać na dostarczenie komunikatu zanim ona ustąpi i zwróci wartość. Argument sendTimeout jest liczbą mikrosekund jaką dajesz funkcji na jej działanie. Jeśli to ograniczenie czasowe jest przekroczone, funkcja nie wykona działań i zwróci błąd (B_TIMED_OUT).
Gdy pytasz aby uzyskać odpowiedź asynchroniczną, mogą być ustawione oddzielne ograniczenia sendTimeout i replyTimeout do wysłania komunikatu i odebrania odpowiedzi. Nie ma żadnego ograniczenia czasowego, gdy wartość przerwy jest ustawiona na B_INFINITE_TIMEOUT - jako że jest ona domyślna. Funkcja nie zablokuje się wcale, jeśli przerwa jest ustawiona na 0.
Jeśli zamiast komunikatu message jest przekazane polecenie command, SendReply() konstruuje BMessage odpowiedzi, inicjalizuje jego daną członkowską what ze stałą polecenia command i wysyła go dokładnie tak jak każda inną odpowiedź. Wesje polecenia command tej funkcji mają nieskończony czasy przerw; blokują one funkcję dopóki komunikat nie jest dostarczony i jeśli żądana odpowiedź jest synchroniczna.
Ta funkcja zwraca B_OK jeśli odpowedź jest wysłana z sukcesem. Jeśli wystąpi problem w wysyłaniu komunikatu, zwraca ona ten sam rodzaj błędu jak SendMessage() BMessenger'a. Może ona również przedstawić określony problem odpowiedzi. Bardziej informacyjne zwracane wartości są przedstawione poniżej:
Kod błędu Jest zwracany gdy następuje B_BAD_REPLY Wysłanie odpowiedzi na komunikat, który nie został jeszcze dostarczony. B_DUPLICATE_REPLY Wysłanie odpowiedzi po tym jak jeden komunikat został już wysłany i dostarczony. B_BAD_THREAD_ID Wysłanie odpowiedzi do wątku przeznaczenia który już nie istnieje. B_BAD_PORT_ID Wysłanie odpowiedzi do BLooper'a i portu który już nie istnieje. B_TIMED_OUT Trwanie dłużej niż określony limit czasu na dostarczenie komunikatu odpowiedzi lub do odbioru odpowiedzi synchronicznej na odpowiedź. Jeśli chcesz opóźnić wysłanie odpowiedzi i zatrzymać obiekt BMessage poza okres jego szeregowania do usunięcia, możesz być w stanie odłączyć go z pętli komunikatu. Popatrz na DetachCurrentMessage() w klasie BLooper.
Popatrz również do: BMessenger::SendMessage(), BLooper::DetachCurrentMessage(), Error, ReturnAddress()
![]() | Unflatten() patrz Flatten() |
![]() | WasDelivered() , IsSourceRemote() , IsSourceWaiting() , IsReply() , Previous() |
bool WasDelivered(void) const bool IsSourceRemote(void) const bool IsSourceWaiting(void) const bool IsReply(void) const const BMessage *Previous(void) const Te funkcje mogą pomóc jeśli jesteś zaangażowany w wymianę komunikatów lub zarządzanie toczącą się komunikacją.
WasDelivered() wskazuje czy jest możliwe wysłanie odpowiedzi na komunikat. Zwraca ona true dla BMessage'a który był posłany, wysłany lub przeciągnięty - to jest taki, który miał być przetworzony przez pętlę komunikatów - i false dla komunikatu który nie został jeszcze dostarczony w żaden sposób.
IsSourceRemote() zwraca true jeśli komunikat miał swoje źródło w innej aplikacji i false jeśłi źródło jest lokalne lub komunikat nie został jeszcze dostarczony.
IsSourceWaiting() zwraca true jeśli źródło komunikatu czeka na odpowiedź synchroniczną i false jeśii nie czeka. Wątek źródła może żądać i oczekiwać odpowiedzi gdy zostanie wywołana funkcja SendMessage() innego BMessenger'a lub funkcja SendReply() BMessage'a.
IsReply() zwraca true jeśli BMessage jest odpowiedzią na poprzedni komunikat (jeśli był wysłany przez funkcję SendReply()) i false jeśli nie jest odpowiedzią.
Previous() zwraca poprzedni komunikat - komunikat na który bieżący BMessage jest odpowiedzią. Działa ona tylko dla BMessage'a który jest odebrany jako odpowiedź asynchroniczna na poprzedni komunikat. Asynchroniczna odpowiedź jest odbierana w kontekście poprzedniego komunikatu, więc nie jest konieczne wywołanie funkcji do jego otrzymania. Ale gdy jest odbierana asynchroniczna odpowiedź, kontekst pierwotnego komunikatu jest gubiony; ta funkcja może go dostarczyć. Previous() zwraca NULL jeśli BMessage nie jest odpowiedzią asynchroniczną na kolejny komunikat.
Popatrz również do: BMessenger::SendMessage(), SendReply(), ReturnAddress()
![]() | WasDropped() , DropPoint() |
bool WasDropped(void) const BPoint DropPoint(BPoint *offset = NULL) const WasDropped() zwraca wartość true jeśli użytkownik dostarczył BMessage przez przeciąganie i upuszczenie i false jeśłi komunikat był przesłany lub wysłany w kodzie aplikacji lub jeśli nie został on jeszcze do wszystkich dostarczony.
DropPoint() podaje punkt, gdzie ulokowany był kursor gdy komunikat został upuszczony (kiedy użytkownik zwolnił przycisk myszy). Zwraca on bezpośrednio punkt w układzie współrzędnych ekranu i jeśli jest dostarczony argument przesunięcia offset, zwraca go przez referencję we współrzędnych opartych na obrazie lub przeciągniętym prostokącie użytkownika. Przesunięcie offset przyjmuje układ współrzędnych z punktem (0.0, 0.0) w lewym górnym rogu przeciąganego prostokąta albo obrazu.
Ponieważ jakiś wartość może być aktualną współrzędną, DropPoint() dostarczy niezawodnych wyników tylko jeśli funkcja WasDropped() zwróciła wartość true.
Popatrz również do: BView::DragMessage()
![]() | = (przypisanie) |
BMessage &operator =(const BMessage&) Przypisuje jeden obiekt BMessage do innego. Po przypisaniu te dwa obiekty są nawzajem duplikatami bez współdzielenia danych.
![]() | new |
void *operator new(size_t numBytes) Rezerwuje (alokuje) pamięć dla obiektu BMessage lub pobiera pamięć z poprzednio zaalokowanego obszaruy podręcznego (cache). Mechanizm korzystający z obszaru podręcznego (caching) jest efektywniejszym sposobem zarządzania pamięcią dla obiektów, które są często tworzone i używane na krótki okres czasu jakimi zwykle są obiekty BMessage.
![]() | delete |
void operator delete(void *memory, size_t numBytes) Zwalnia pamięć zarezerwowaną przez wersję new BMessage'a i może mieć zamiar przywrócenia pamięci do obszaru podręcznego (cache).
* Określenie spłaszczony (ang. flattened) oznacza, że obiekt (egzemplarz danej klasy) jest traktowany (zapis, odczyt, przechowywanie) jak ciąg danych binarnych w umieszczony w buforze pamięci w postaci ciągu bajtów bez określonej struktury a nie obiekt który posiada dane i funkcje członkowskie (właściwości i metody).
|
Be
Book,
...w ślicznym HTML...
dla BeOS wydanie 5
Copyright © 2000 Be, Inc. Wszelkie prawa zastrzeżone.