85 lines
13 KiB
HTML
85 lines
13 KiB
HTML
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
||
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>The Be Book - System Overview - The Application Kit</title><link rel="stylesheet" href="be_book.css" type="text/css" media="all" /><link rel="shortcut icon" type="image/vnd.microsoft.icon" href="./images/favicon.ico" /><!--[if IE]>
|
||
<link rel="stylesheet" type="text/css" href="be_book_ie.css" />
|
||
<![endif]--><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><meta name="keywords" content="Access, BeOS, BeBook, API" /><link rel="start" href="index.html" title="The Be Book" /><link rel="up" href="TheApplicationKit_Overview.html" title="The Application Kit" /><link rel="prev" href="BLooper_Overview.html" title="BLooper" /><link rel="next" href="BMessageFilter_Overview.html" title="BMessageFilter" /></head><body><div id="header"><div id="headerT"><div id="headerTL"><a accesskey="p" href="BLooper_Overview.html" title="BLooper"><img src="./images/navigation/prev.png" alt="Prev" /></a> <a accesskey="u" href="TheApplicationKit_Overview.html" title="The Application Kit"><img src="./images/navigation/up.png" alt="Up" /></a> <a accesskey="n" href="BMessageFilter_Overview.html" title="BMessageFilter"><img src="./images/navigation/next.png" alt="Next" /></a></div><div id="headerTR"><div id="navigpeople"><a href="http://www.haiku-os.org"><img src="./images/People_24.png" alt="haiku-os.org" title="Visit The Haiku Website" /></a></div><div class="navighome" title="Home"><a accesskey="h" href="index.html"><img src="./images/navigation/home.png" alt="Home" /></a></div><div class="navigboxed" id="navigindex"><a accesskey="i" href="ClassIndex.html" title="Index">I</a></div><div class="navigboxed" id="naviglang" title="English">en</div></div><div id="headerTC">The Be Book - System Overview - The Application Kit</div></div><div id="headerB">Prev: <a href="BLooper_Overview.html">BLooper</a> Up: <a href="TheApplicationKit_Overview.html">The Application Kit</a> Next: <a href="BMessageFilter_Overview.html">BMessageFilter</a></div><hr /></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h2 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BMessage_Overview"></a>BMessage</h2></div></div></div><a id="id433871" class="indexterm"></a><p>
|
||
A <a class="link" href="BMessage.html" title="BMessage"><code class="classname">BMessage</code></a> is a bundle of structured information.
|
||
Every <a class="link" href="BMessage.html" title="BMessage"><code class="classname">BMessage</code></a> contains a command constant and some
|
||
number of data fields.
|
||
</p><ul class="itemizedlist"><li><p>
|
||
The command constant is an <span class="type">int32</span> value that describes,
|
||
roughly, the purpose of the
|
||
<a class="link" href="BMessage.html" title="BMessage"><code class="classname">BMessage</code></a>.
|
||
It's stored as
|
||
the public <code class="varname">what</code> data member. You always set and examine
|
||
the <code class="varname">what</code> value directly, you don't need to call a
|
||
function. (As a convenience, you can set the command constant when you
|
||
create your <a class="link" href="BMessage.html" title="BMessage"><code class="classname">BMessage</code></a> object.)
|
||
</p></li><li><p>
|
||
The data fields are name-type-value triplets. A field is be primarily
|
||
identified by name, but you can look for fields by name, type, or a
|
||
combination of the two. The type is encoded as a constant
|
||
(<code class="constant">B_INT32_TYPE</code>, <code class="constant">B_STRING_TYPE</code>
|
||
etc), and is meant to describe the type of value that the field holds. A
|
||
single field can have only one name and one type, but can contain an array
|
||
of values. Individual values in a field are accessible by index.
|
||
</p></li></ul><p>
|
||
Neither the command constant nor the data fields are mandatory. You can
|
||
create a <a class="link" href="BMessage.html" title="BMessage"><code class="classname">BMessage</code></a> that has data but no command, or
|
||
that <span class="italic">only</span> has a command. However,
|
||
creating a <a class="link" href="BMessage.html" title="BMessage"><code class="classname">BMessage</code></a> that has neither is pointless.
|
||
</p><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><hr /><div xmlns:d="http://docbook.org/ns/docbook"><h3 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BMessage_Overview_PreparatoryReading"></a>Preparatory Reading</h3></div></div></div><p>
|
||
<a class="link" href="BMessage.html" title="BMessage"><code class="classname">BMessage</code></a>s are used throughout the kits to send data
|
||
(or notifications) to another threadpossibly in another application. To
|
||
understand how <a class="link" href="BMessage.html" title="BMessage"><code class="classname">BMessage</code></a>s fit into the messaging
|
||
system, see "<a class="link" href="TheApplicationKit_Messaging.html" title="Messaging">Messaging</a>".
|
||
</p><p>
|
||
The <a class="link" href="BMessage.html" title="BMessage"><code class="classname">BMessage</code></a> class also contributes a number of
|
||
functions that help define the scripting system. See "<a class="link" href="TheApplicationKit_Scripting.html" title="Scripting">Scripting</a>" for an
|
||
introduction to this system.
|
||
</p><p>
|
||
<a class="link" href="BMessage.html" title="BMessage"><code class="classname">BMessage</code></a>s are also used by a number of classes
|
||
(<a class="link" href="BClipboard.html" title="BClipboard"><code class="classname">BClipboard</code></a>, <a class="link" href="BArchivable.html" title="BArchivable"><code class="classname">BArchivable</code></a>, and
|
||
others) for their ability to store data.
|
||
</p></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><hr /><div xmlns:d="http://docbook.org/ns/docbook"><h3 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BMessage_Overview_TypesOfFunctions"></a>Types of Functions</h3></div></div></div><p>
|
||
The <a class="link" href="BMessage.html" title="BMessage"><code class="classname">BMessage</code></a> class defines five types of functions:
|
||
</p><dl class="variablelist"><dt><span class="term">Data field functions.</span></dt><dd><p>These functions either set or retrieve the value of a data field. See
|
||
<a class="link" href="BMessage.html#BMessage_AddData" title="AddData(), AddBool(), AddInt8(), AddInt16(), AddInt32(), AddInt64(), AddFloat(), AddDouble(), AddString(), AddPoint(), AddRect(), AddRef(), AddMessage(), AddMessenger(), AddPointer(), AddFlat()"><code class="methodname">AddData()</code></a>,
|
||
<a class="link" href="BMessage.html#BMessage_FindData" title="FindData(), FindBool(), FintInt8(), FindInt16(), FindInt32(), FindInt64(), FindFloat(), FindDouble(), FindString(), FindPoint(), FindRect(), FindRef(), FindMessage(), FindMessenger(), FindPointer(), FindFlat()"><code class="methodname">FindData()</code></a>,
|
||
<a class="link" href="BMessage.html#BMessage_ReplaceData" title="ReplaceData(), ReplaceBool(), ReplaceInt8(), ReplaceInt16(), ReplaceInt32(), ReplaceInt64(), ReplaceFloat(), ReplaceDouble(), ReplaceString(), ReplacePoint(), ReplaceRect(), ReplaceRef(), ReplaceMessage(), ReplaceMessenger(), ReplacePointer(), ReplaceFlat()"><code class="methodname">ReplaceData()</code></a>,
|
||
and
|
||
<a class="link" href="BMessage.html#BMessage_RemoveName" title="RemoveName(), RemoveData()"><code class="methodname">RemoveName()</code></a>.</p></dd><dt><span class="term">Info functions.</span></dt><dd><p>These functions retrieve information about the state and contents of the
|
||
<a class="link" href="BMessage.html" title="BMessage"><code class="classname">BMessage</code></a>. See
|
||
<a class="link" href="BMessage.html#BMessage_IsSystem" title="IsSystem()"><code class="methodname">IsSystem()</code></a> and
|
||
<a class="link" href="BMessage.html#BMessage_GetInfo" title="GetInfo()"><code class="methodname">GetInfo()</code></a>.</p></dd><dt><span class="term">Messaging functions.</span></dt><dd><p>These functions are part of the
|
||
messaging system. A smaller set of functions reports on the status of a
|
||
received message. For example,
|
||
<a class="link" href="BMessage.html#BMessage_IsSourceWaiting"><code class="methodname">IsSourceWaiting()</code></a>
|
||
tells whether the message sender is waiting for a reply,
|
||
<a class="link" href="BMessage.html#BMessage_WasDropped" title="WasDropped(), DropPoint()"><code class="methodname">WasDropped()</code></a>
|
||
says whether it was dragged and dropped, and
|
||
<a class="link" href="BMessage.html#BMessage_DropPoint"><code class="methodname">DropPoint()</code></a>
|
||
says where it was dropped.</p></dd><dt><span class="term">Scripting functions.</span></dt><dd><p>Functions such as
|
||
<a class="link" href="BMessage.html#BMessage_AddSpecifier" title="AddSpecifier()"><code class="methodname">AddSpecifier()</code></a>
|
||
and
|
||
<a class="link" href="BMessage.html#BMessage_PopSpecifier"><code class="methodname">PopSpecifier()</code></a>.</p></dd><dt><span class="term">Flattening functions.</span></dt><dd><p>The data in a
|
||
<a class="link" href="BMessage.html" title="BMessage"><code class="classname">BMessage</code></a>
|
||
can be flattened into an untyped stream of bytes. See
|
||
<a class="link" href="BMessage.html#BMessage_Flatten" title="Flatten(), Unflatten(), FlattenedSize()"><code class="methodname">Flatten()</code></a>.</p></dd></dl></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><hr /><div xmlns:d="http://docbook.org/ns/docbook"><h3 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BMessage_Overview_Ownership"></a>BMessage Ownership</h3></div></div></div><p>
|
||
The documentation for the functions that accept or pass back a
|
||
<a class="link" href="BMessage.html" title="BMessage"><code class="classname">BMessage</code></a> object should tell you who's responsible
|
||
for deleting the object. Most functions that accept a
|
||
<a class="link" href="BMessage.html" title="BMessage"><code class="classname">BMessage</code></a> argument copy the object, leaving the
|
||
caller with the responsibility for deleting the argument. The exceptions
|
||
i.e. <a class="link" href="BMessage.html" title="BMessage"><code class="classname">BMessage</code></a>-accepting functions that take over
|
||
ownership of the object are listed below:
|
||
</p><p>
|
||
Functions that return a <a class="link" href="BMessage.html" title="BMessage"><code class="classname">BMessage</code></a> to you usually
|
||
don't give up ownership; in general, you don't delete the
|
||
<a class="link" href="BMessage.html" title="BMessage"><code class="classname">BMessage</code></a>s that are passed to you. The exceptions,
|
||
functions that expect the caller to take over ownership of a passed-back
|
||
<a class="link" href="BMessage.html" title="BMessage"><code class="classname">BMessage</code></a>,are listed below:
|
||
</p></div></div><div id="footer"><hr /><div id="footerT">Prev: <a href="BLooper_Overview.html">BLooper</a> Up: <a href="TheApplicationKit_Overview.html">The Application Kit</a> Next: <a href="BMessageFilter_Overview.html">BMessageFilter</a> </div><div id="footerB"><div id="footerBL"><a href="BLooper_Overview.html" title="BLooper"><img src="./images/navigation/prev.png" alt="Prev" /></a> <a href="TheApplicationKit_Overview.html" title="The Application Kit"><img src="./images/navigation/up.png" alt="Up" /></a> <a href="BMessageFilter_Overview.html" title="BMessageFilter"><img src="./images/navigation/next.png" alt="Next" /></a></div><div id="footerBR"><div><a href="http://www.haiku-os.org"><img src="./images/People_24.png" alt="haiku-os.org" title="Visit The Haiku Website" /></a></div><div class="navighome" title="Home"><a accesskey="h" href="index.html"><img src="./images/navigation/home.png" alt="Home" /></a></div></div><div id="footerBC"><a href="http://www.access-company.com/home.html" title="ACCESS Co."><img alt="Access Company" src="./images/access_logo.png" /></a></div></div></div><div id="licenseFooter"><div id="licenseFooterBL"><a rel="license" href="http://creativecommons.org/licenses/by-nc-nd/3.0/" title="Creative Commons License"><img alt="Creative Commons License" style="border-width:0" src="https://licensebuttons.net/l/by-nc-nd/3.0/88x31.png" /></a></div><div id="licenseFooterBR"><a href="./LegalNotice.html">Legal Notice</a></div><div id="licenseFooterBC"><span id="licenseText">This work is licensed under a
|
||
<a rel="license" href="http://creativecommons.org/licenses/by-nc-nd/3.0/">Creative
|
||
Commons Attribution-Non commercial-No Derivative Works 3.0 License</a>.</span></div></div></body></html>
|