nephele
/
haiku-website
0
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity
haiku-website/static/legacy-docs/bebook/TheSupportKit_Functions.html

436 lines
46 KiB
HTML
Raw Permalink Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<?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 - Classes And Methods - The Support 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="TheSupportKit.html" title="The Support Kit" /><link rel="prev" href="BString.html" title="BString" /><link rel="next" href="TheSupportKit_Constants.html" title="Constants" /></head><body><div id="header"><div id="headerT"><div id="headerTL"><a accesskey="p" href="BString.html" title="BString"><img src="./images/navigation/prev.png" alt="Prev" /></a> <a accesskey="u" href="TheSupportKit.html" title="The Support Kit"><img src="./images/navigation/up.png" alt="Up" /></a> <a accesskey="n" href="TheSupportKit_Constants.html" title="Constants"><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 - Classes And Methods - The Support Kit</div></div><div id="headerB">Prev: <a href="BString.html">BString</a>  Up: <a href="TheSupportKit.html">The Support Kit</a>  Next: <a href="TheSupportKit_Constants.html">Constants</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="TheSupportKit_Functions"></a>Functions and Macros</h2></div></div></div><p>
Library: <code class="filename">libbe.so</code>
</p><p>
This section lists the Support Kit's general-purpose functions and macros.
</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="atomic_add"></a><a id="atomic_and"></a>
<a id="atomic_or"></a>
atomic_add(), atomic_and(), atomic_or()</h3></div></div></div><a id="id1281967" class="indexterm"></a><a id="id1281974" class="indexterm"></a><a id="id1281981" class="indexterm"></a><p>
Declared In: <code class="filename">support/SupportDefs.h</code>
</p><code class="methodsynopsis c"><span class="type">int32 </span><span class="methodname">atomic_add</span>(<span class="methodparam"><span class="type">vint32* </span><span class="parameter">atomicVariable</span></span>,<br />                 <span class="methodparam"><span class="type">int32 </span><span class="parameter">addValue</span></span>);</code><code class="methodsynopsis c"><span class="type">int32 </span><span class="methodname">atomic_and</span>(<span class="methodparam"><span class="type">vint32* </span><span class="parameter">atomicVariable</span></span>,<br />                 <span class="methodparam"><span class="type">int32 </span><span class="parameter">andValue</span></span>);</code><code class="methodsynopsis c"><span class="type">int32 </span><span class="methodname">atomic_or</span>(<span class="methodparam"><span class="type">vint32* </span><span class="parameter">atomicVariable</span></span>,<br />                <span class="methodparam"><span class="type">int32 </span><span class="parameter">orValue</span></span>);</code><p>
These functions perform the named operations (addition, bitwise AND, or
bitwise OR) on the 32-bit value found in <code class="parameter">atomicVariable</code>, thus:
</p><pre class="programlisting example c">*<code class="parameter">atomicVariable</code> += <code class="parameter">addValue</code>
*<code class="parameter">atomicVariable</code> &amp;= <code class="parameter">andValue</code>
*<code class="parameter">atomicVariable</code> |= <code class="parameter">orValue</code></pre><p>
Each function returns the previous value of the <span class="type">vint32</span> variable that
<code class="parameter">atomicVariable</code> points to (in other words, they each return the value that
was in <span class="code">*<code class="parameter">atomicVariable</code></span> before the operation was performed).
</p><p>
These functions are guaranteed to be atomic: if two threads attempt to
access the same atomic variable at the same time (through these
functions), one of the two threads will be made to wait until the other
thread has completed the operation and updated the
<code class="parameter">atomicVariable</code> value.
</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="beep"></a><a id="add_system_beep_event"></a>
<a id="system_beep"></a>
beep(), system_beep(), add_system_beep_event()</h3></div></div></div><a id="id1282181" class="indexterm"></a><a id="id1282188" class="indexterm"></a><a id="id1282195" class="indexterm"></a><p>
Declared In: <code class="filename">support/Beep.h</code>
</p><code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">beep</span>();</code><code class="methodsynopsis c"><span class="type">status_t </span><span class="methodname">system_beep</span>(<span class="methodparam"><span class="type">char* </span><span class="parameter">eventName</span></span>,<br />                     <span class="methodparam"><span class="type">uint32 </span><span class="parameter">flags</span><span class="initializer"> = 0</span></span>);</code><p>
<code class="function">beep()</code> produces the basic system beep. This function engages the Media
Server, but doesn't wait for the sound to play. If it can't contact the
server to play the beep, it returns <code class="constant">B_ERROR</code>. If it can make contact but
can't get a satisfactory reply back from the server, it returns
<code class="constant">B_BAD_REPLY</code>. Otherwise, it returns <code class="constant">B_OK</code>.
</p><p>
<code class="function">system_beep()</code> plays the system beep configured for the event specified by
the given <code class="parameter">eventName</code>.
</p><p>
Applications can add new system beep events by calling
<code class="function">add_system_beep_event()</code>, passing the name to assign the event; the <code class="parameter">flags</code>
argument is currently unused and should be zero. Once this has been done,
the user can use the Sounds preference application to configure a sound
for the event.
</p><p>
See also: <a class="link" href="TheMediaKit_Functions.html#play_sound" title="play_sound()"><code class="function">play_sound()</code></a> in the Media Kit
</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="Macros_cast_as"></a><a id="Macros_class_name"></a>
<a id="Macros_is_instance_of"></a>
<a id="Macros_is_kind_of"></a>
class_name(), is_instance_of(), is_kind_of(), cast_as()</h3></div></div></div><p>Declared In: <code class="filename">support/ClassInfo.h</code></p><code class="methodsynopsis c"><span class="type">char* </span><span class="methodname">class_name</span>(<span class="methodparam"><span class="parameter">object</span></span>);</code><code class="methodsynopsis c"><span class="type">bool </span><span class="methodname">is_instance_of</span>(<span class="methodparam"><span class="parameter">object</span></span>,<br />                    <span class="methodparam"><span class="parameter">class</span></span>);</code><code class="methodsynopsis c"><span class="type">bool </span><span class="methodname">is_kind_of</span>(<span class="methodparam"><span class="parameter">object</span></span>,<br />                <span class="methodparam"><span class="parameter">class</span></span>);</code><code class="methodsynopsis c"><span class="type">class* </span><span class="methodname">cast_as</span>(<span class="methodparam"><span class="parameter">object</span></span>,<br />               <span class="methodparam"><span class="parameter">class</span></span>);</code><p>
These macros deliver information about an object's type, including the
name of its class and its standing in the class hierarchy. In each case,
the object argument is a pointer to an object; it can be an object of any
type (it doesn't have to descend from any particular class). The class
argument is a class name—not a string such as "<code class="classname">BApplication</code>", but
the type name itself (literally <code class="classname">BApplication</code>).
</p><p>
<code class="methodname">class_name()</code> returns a pointer to the name of object's class.
</p><p>
<code class="methodname">is_instance_of()</code> returns <code class="constant">true</code> if object is an instance of class, and
<code class="constant">false</code> otherwise.
</p><p>
<code class="methodname">is_kind_of()</code> returns <code class="constant">true</code> if object is an instance of class or an
instance of any class that inherits from class, and <code class="constant">false</code> if not.
</p><p>
<code class="methodname">cast_as()</code> returns a pointer
to object cast as a pointer to an object of
class, but only if object is a kind of class. If not, object cannot be
safely cast as a pointer to class, so
<code class="methodname">cast_as()</code> returns <code class="constant">NULL</code>.
</p><p>
For example, given this slice of the inheritance hierarchy from the
Interface Kit, and code like this that creates an instance of the
<code class="classname">BPictureButton</code> class,
</p><pre class="programlisting example cpp"><code class="classname">BButton</code>* <code class="varname">anObject</code> = new <code class="classname">BPictureButton</code>(...);</pre><p>
the first three macros would work as follows:
</p><ul class="itemizedlist"><li><p>
The <code class="function">class_name()</code> macro would return a pointer to the string
"BPictureButton":
</p><pre class="programlisting example c"><span class="type">const char *</span><code class="varname">s</code> = <code class="function">class_name</code>(<code class="varname">anObject</code>);</pre></li><li><p>
The <code class="function">is_instance_of()</code> macro would return
<code class="constant">true</code> only if the <code class="parameter">class</code> passed to it is
<a class="link" href="BPictureButton.html" title="BPictureButton"><code class="classname">BPictureButton</code></a>. In
the following example, it would return <code class="constant">false</code>, and the
message would not be printed. Even though
<a class="link" href="BPictureButton.html" title="BPictureButton"><code class="classname">BPictureButton</code></a>
inherits from <a class="link" href="BView.html" title="BView"><code class="classname">BView</code></a>,
the object is an instance of the
<a class="link" href="BPictureButton.html" title="BPictureButton"><code class="classname">BPictureButton</code></a>
class, not <a class="link" href="BView.html" title="BView"><code class="classname">BView</code></a>:
</p><pre class="programlisting example cpp">if ( <code class="function">is_instance_of</code>(anObject, <code class="classname">BView</code>) )
<code class="function">printf</code>("The object is an instance of BView.\n");</pre></li><li><p>
The <code class="function">is_kind_of()</code> macro would return
<code class="constant">true</code> if <code class="parameter">class</code> is
<a class="link" href="BPictureButton.html" title="BPictureButton"><code class="classname">BPictureButton</code></a>
or any class that
<a class="link" href="BPictureButton.html" title="BPictureButton"><code class="classname">BPictureButton</code></a>
inherits from. In the following
example, it would return true and the message would be printed. A
<a class="link" href="BPictureButton.html" title="BPictureButton"><code class="classname">BPictureButton</code></a>
is a kind of <a class="link" href="BView.html" title="BView"><code class="classname">BView</code></a>:
</p><pre class="programlisting example cpp">if ( <code class="function">is_kind_of</code>(anObject, <code class="classname">BView</code>) )
<code class="function">printf</code>("The object is a kind of BView.\n");</pre></li></ul><p>
Note that class names are not passed as strings, but <code class="function">class_name()</code> returns
the name as a string.
</p><p>
The <code class="function">cast_as()</code> macro is most useful when you want to treat a generic
object as an instance of a more specific class. Suppose, for example,
that the <a class="link" href="BPictureButton.html" title="BPictureButton"><code class="classname">BPictureButton</code></a>
mentioned above becomes the focus view for a
window and you retrieve it by calling the
<a class="link" href="BWindow.html" title="BWindow"><code class="classname">BWindow</code></a>'s
<a class="link" href="BWindow.html#BWindow_CurrentFocus" title="CurrentFocus()"><code class="methodname">CurrentFocus()</code></a>
function:
</p><pre class="programlisting example cpp"><code class="classname">BView</code>* <code class="varname">focus</code> = <code class="varname">myWindow</code>-&gt;<code class="methodname">CurrentFocus()</code>;</pre><p>
Since the focus view might be any type of view,
<a class="link" href="BWindow.html#BWindow_CurrentFocus" title="CurrentFocus()"><code class="methodname">CurrentFocus()</code></a>
returns a pointer to an object of the base
<a class="link" href="BView.html" title="BView"><code class="classname">BView</code></a> class. Unless you know otherwise,
you cannot treat the object as anything more specific than a
<a class="link" href="BView.html" title="BView"><code class="classname">BView</code></a>
instance. However, you can ask the object if it's a kind of
<a class="link" href="BPictureButton.html" title="BPictureButton"><code class="classname">BPictureButton</code></a>
and, if it is, cast it to the
<a class="link" href="BPictureButton.html" title="BPictureButton"><code class="classname">BPictureButton</code></a> type:
</p><pre class="programlisting example cpp">if ( <code class="function">is_kind_of</code>(focus, <code class="classname">BPictureButton</code>) ) {
<code class="classname">BPictureButton</code>* <code class="varname">picbutton =</code> (<code class="classname">BPictureButton</code> *)<code class="varname">focus</code>);
if ( <code class="varname">picbutton</code>-&gt;<code class="methodname">Behavior()</code> == <code class="constant">B_TWO_STATE_BUTTON</code> )
. . .
}</pre><p>
The <code class="function">cast_as()</code> macro does the same thing, but more efficiently. It casts
the object to the target class if it is safe to do so—if the object
is an instance of a class that inherits from the target class or an
instance of the target class itself—and returns <code class="constant">NULL</code> if not.
</p><pre class="programlisting example cpp"><code class="classname">BPictureButton</code>* <code class="varname">picbutton</code> = <code class="function">cast_as</code>(<code class="varname">focus</code>, <code class="classname">BPictureButton</code>);
if ( <code class="varname">picbutton</code> ) {
if ( <code class="varname">picbutton</code>-&gt;<code class="methodname">Behavior()</code> == <code class="constant">B_TWO_STATE_BUTTON</code> )
. . .
}</pre><p>
<code class="function">cast_as()</code> is often used in place of the cast operator to assure code
safety even where an expected result is anticipated and there's no need
for an intermediate variable (like <code class="varname">focus</code>):
</p><pre class="programlisting example cpp"><code class="classname">BPictureButton</code>* <code class="varname">picbutton</code> =
<code class="function">cast_as</code>(<code class="varname">myWindow</code>-&gt;<code class="methodname">CurrentFocus()</code>, <code class="classname">BPictureButton</code>);
if ( <code class="varname">picbutton</code> ) {
. . .
}</pre><p>
The <code class="function">cast_as()</code> and
<code class="function">is_kind_of()</code> macros work alike; they're both based on
the C++ dynamic_cast operator and they reflect its behavior. To describe
that behavior more precisely, let's adopt the following shorthand terms
for an object's type:
</p><ul class="itemizedlist"><li><p>
The real type of an object is its type on construction. For example,
if you construct an instance of the BButton class, as shown above,
<a class="link" href="BButton.html" title="BButton"><code class="classname">BButton</code></a> is its real type.
</p></li><li><p>
The declared type of an object is the class label it currently bears.
For example, <code class="methodname">CurrentFocus()</code> returns an object whose declared class is
<a class="link" href="BView.html" title="BView"><code class="classname">BView</code></a>.
</p></li></ul><p>
Either of these types can be compared to a target type, the type you want
to cast the object to or test it against. The target type is the class
argument passed to the macros.
</p><p>
In the best of all possible worlds, you'd want to ignore the declared
type of an object and compare only the real type to the target type.
However, the dynamic_cast operator—and by extension <code class="function">cast_as()</code> and
<code class="function">is_kind_of()</code>—considers the real type only if it has to. It first
compares the object's declared type to the target type. It assumes that
the declared type is accurate (that the object is truly the kind of
object it's represented to be) and it summarily handles the obvious
cases: If the target type is the same as the declared type or if it's a
class that the declared type inherits from, the operation will succeed.
Consequently, <code class="function">cast_as()</code> will cast the object to the target type and
<code class="function">is_kind_of()</code> will return true, regardless of the object's real type. In
other words, if the target class is above or at the same level as the
declared class in the inheritance hierarchy, the real class is ignored.
</p><p>
However, if the declared type doesn't match or derive from the target
type, <span class="code">dynamic_cast</span> and the macros look at the real type: If the target
class is identical to the real type, or if it's a class that the real
type derives from, the operation succeeds. If not, it fails.
</p><p>
Therefore, the <code class="function">is_kind_of()</code> and
<code class="function">cast_as()</code> macros will produce reliable
results as long as objects are not arbitrarily cast to types that may not
be accurate. For example, you should not cast an object to a target type
and then attempt to use <code class="function">is_kind_of()</code> to determine if the cast was
correct. This code is unreliable:
</p><pre class="programlisting example cpp"><code class="classname">BPictureButton</code>* <code class="varname">picbutton</code> =
(<code class="classname">BPictureButton</code>*)<code class="varname">myWindow</code>-&gt;<code class="methodname">CurrentFocus()</code>;
if ( <code class="function">is_kind_of</code>(<code class="varname">picbutton</code>, <code class="classname">BPictureButton</code>) ) {
. . .
}</pre><p>
In this example, <code class="function">is_kind_of()</code>
will always return <code class="constant">true</code>, no matter what the
class of the current focus view. The general rule is that the declared
type of an object must always be accurate; an object should be typed only
to its own class or to a class that it inherits from. The macros cannot
rescue you from an inaccurate cast.
</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="convert_to_utf8"></a><a id="convert_from_utf8"></a>
convert_to_utf8(), convert_from_utf8()</h3></div></div></div><a id="id1283227" class="indexterm"></a><a id="id1283234" class="indexterm"></a><p>
Declared in: <code class="filename">support/UTF8.h</code>
</p><code class="methodsynopsis c"><span class="type">status_t </span><span class="methodname">convert_to_utf8</span>(<span class="methodparam"><span class="type">uint32 </span><span class="parameter">sourceEncoding</span></span>,<br />                         <span class="methodparam"><span class="modifier">const </span><span class="type">char* </span><span class="parameter">source</span></span>,<br />                         <span class="methodparam"><span class="type">int32* </span><span class="parameter">sourceLength</span></span>,<br />                         <span class="methodparam"><span class="type">char* </span><span class="parameter">destination</span></span>,<br />                         <span class="methodparam"><span class="type">int32* </span><span class="parameter">destinationLength</span></span>,<br />                         <span class="methodparam"><span class="type">int32* </span><span class="parameter">state</span></span>,<br />                         <span class="methodparam"><span class="type">char </span><span class="parameter">substitute</span><span class="initializer"> = <span class="constant">B_SUBSTITUTE</span></span></span>);</code><code class="methodsynopsis c"><span class="type">status_t </span><span class="methodname">convert_from_utf8</span>(<span class="methodparam"><span class="type">uint32 </span><span class="parameter">destinationEncoding</span></span>,<br />                           <span class="methodparam"><span class="modifier">const </span><span class="type">char* </span><span class="parameter">source</span></span>,<br />                           <span class="methodparam"><span class="type">int32* </span><span class="parameter">sourceLength</span></span>,<br />                           <span class="methodparam"><span class="type">char* </span><span class="parameter">destination</span></span>,<br />                           <span class="methodparam"><span class="type">int32* </span><span class="parameter">destinationLength</span></span>,<br />                           <span class="methodparam"><span class="type">int32* </span><span class="parameter">state</span></span>,<br />                           <span class="methodparam"><span class="type">char </span><span class="parameter">substitute</span><span class="initializer"> = <span class="constant">B_SUBSTITUTE</span></span></span>);</code><p>
These functions convert text to and from the <span class="trademark">Unicode</span>™ UTF-8 encoding
that's standard for the Be operating system and is assumed in most
contexts. UTF-8 is described under
"<a class="xref" href="TheInterfaceKit_Character_Encoding.html" title="Character Encoding">Character Encoding</a>" section of The Interface Kit chapter.
</p><p>
<code class="function">convert_to_utf8()</code> permits you to take text that's encoded according to
another standard and convert it to UTF-8 for the BeOS.
<code class="function">convert_from_utf8()</code> lets you convert text from UTF-8 to other encodings
for other venues (for example, to the encodings commonly used for
displaying text on the World Wide Web).
</p><p>
The first argument passed to these functions names the other
encoding&amp;#8212;the source encoding for <code class="function">convert_to_utf8()</code> and the
destination encoding for <code class="function">convert_from_utf8()</code>. It can be any of the
following constants:
</p><div class="informaltable"><table border="1"><colgroup><col /><col /></colgroup><tbody><tr><td><code class="constant">B_ISO1_CONVERSION</code></td><td><code class="constant">B_MAC_ROMAN_CONVERSION</code></td></tr><tr><td><code class="constant">B_ISO2_CONVERSION</code></td><td><code class="constant">B_SJIS_CONVERSION</code></td></tr><tr><td><code class="constant">B_ISO3_CONVERSION</code></td><td><code class="constant">B_EUC_CONVERSION</code></td></tr><tr><td><code class="constant">B_ISO4_CONVERSION</code></td><td><code class="constant">B_JIS_CONVERSION</code></td></tr><tr><td><code class="constant">B_ISO5_CONVERSION</code></td><td><code class="constant">B_MS_WINDOWS_CONVERSION</code></td></tr><tr><td><code class="constant">B_ISO6_CONVERSION</code></td><td><code class="constant">B_UNICODE_CONVERSION</code></td></tr><tr><td><code class="constant">B_ISO7_CONVERSION</code></td><td><code class="constant">B_KOI8R_CONVERSION</code></td></tr><tr><td><code class="constant">B_ISO8_CONVERSION</code></td><td><code class="constant">B_MS_WINDOWS_1251_CONVERSION</code></td></tr><tr><td><code class="constant">B_ISO9_CONVERSION</code></td><td><code class="constant">B_MS_DOS_866_CONVERSION</code></td></tr><tr><td><code class="constant">B_ISO10_CONVERSION</code></td><td><code class="constant"> </code></td></tr></tbody></table></div><p>
Most of these constants designate encoding schemes that are supported by
the <a class="link" href="BFont.html" title="BFont"><code class="classname">BFont</code></a> class in
the Interface Kit and its
<a class="link" href="BFont.html#BFont_SetEncoding" title="SetEncoding() , Encoding()"><code class="methodname">SetEncoding()</code></a> function. They
parallel the constants that are passed to that function. For example,
<code class="constant">B_ISO1_CONVERSION</code> (for these functions) and <code class="constant">B_ISO_8859_1</code> (for
<a class="link" href="BFont.html#BFont_SetEncoding" title="SetEncoding() , Encoding()"><code class="methodname">SetEncoding()</code></a>)
both designate the extended <acronym class="acronym">ASCII</acronym> encoding defined in part
one of ISO 8859 (Latin 1). Similarly, <code class="constant">B_ISO2_CONVERSION</code> matches
<code class="constant">B_ISO_8859_2</code>, <code class="constant">B_ISO3_CONVERSION</code> matches <code class="constant">B_ISO_8859_3</code>, and so on.
<code class="constant">B_MAC_ROMAN_CONVERSION</code> matches <code class="constant">B_MACINTOSH_ROMAN</code>. (<code class="constant">B_ISO10_CONVERSION</code> is
not implemented for this release.)
</p><p>
<code class="constant">B_SJIS_CONVERSION</code> stands for the Shift-JIS (Japanese Industrial Standard)
encoding of Japanese and <code class="constant">B_EUC_CONVERSION</code> stands for the EUC (Extended
UNIX Code) encoding of Japanese in packed format.
</p><p>
Both functions convert up to <code class="parameter">sourceLength</code> bytes of text from the source
buffer. They write up to <code class="parameter">destinationLength</code> bytes of converted text into
the destination buffer. The amount of text that they actually convert is
therefore constrained both by the amount of source text (<code class="parameter">sourceLength</code>)
and the capacity of the output buffer (<code class="parameter">destinationLength</code>). Neither
function stops at a null terminator ('0') when reading the input buffer
nor adds one to the text in the output buffer; they depend only on
<code class="parameter">sourceLength</code> and <code class="parameter">destinationLength</code> for guidance.
</p><p>
When finished, these functions modify the variable that <code class="parameter">sourceLength</code>
refers to so that it reports the number of bytes of source text actually
converted. They also modify the variable that <code class="parameter">destinationLength</code> refers to
so that it reports the number of bytes actually written to the
destination buffer. Neither function will stop in the middle of a
multibyte source character; they're guaranteed to convert only full
characters.
</p><p>
The <code class="parameter">state</code> argument serves as a cookie that lets you use multiple calls to
these functions to convert a batch of text (if, for example, the text is
stored in multiple buffers). Pass 0 for the first buffer, and pass the
value returned in state to the next call to continue processing the same
text; this will cause the conversion to continue where it left off. For
example:
</p><pre class="programlisting example c"><span class="comment">/* buffer is a pointer to a small source buffer */</span>
<span class="comment">/* destBuffer is a pointer to a small destination buffer */</span>
<span class="comment">/* destBufferLen is the size of the destination buffer in bytes */</span>
<span class="type">int32</span> <code class="varname">state</code> = 0;
<span class="type">int32</span> <code class="varname">bufferLen</code>;
while ((<code class="varname">bufferLen</code> = <code class="methodname">GetNextBuffer</code>(<code class="varname">file</code>, <code class="varname">buffer</code>))) {
<code class="function">convert_to_utf8</code>(<code class="varname">buffer</code>, &amp;amp;<code class="varname">bufferLen</code>, <code class="varname">destBuffer</code>, &amp;amp;<code class="varname">destBufferLen</code>,
&amp;amp;<code class="varname">state</code>);
<span class="comment">/* do stuff with the buffer in destBuffer, which has the converted
text */</span>
}
</pre><p>
In this example, text is fetched using a call to a function called
<code class="methodname">GetNextBuffer()</code>, whose implementation depends on the application's needs.
Each buffer is converted, and the converted text is stored in destBuffer,
which can then be used by the application.
</p><p>
If either function encounters a character in the source that the
destination format doesn't allow, it puts the character specified by the
substitute argument (or a question mark ('?') if substitute isn't
specified) in its place in the output text. This is much more likely to
occur when converting from UTF-8 than when converting to it, since
Unicode represents a very large number of characters.
</p><p>
If successful in converting at least one source character, both functions
return <code class="constant">B_OK</code>. If unsuccessful, for example, if they don't recognize the
source or destination encoding, they return <code class="constant">B_ERROR</code>. If there's an error,
you should not trust any of the output arguments.
</p><div class="admonition note"><div class="title">Note</div><div class="graphic"><img class="icon" alt="Note" width="32" src="./images/admonitions/Info_32.png" /><div class="text"><p>These functions are found in the
<code class="filename">libtextencoding.so</code> library. If you use
them, be sure to include this library file.</p></div></div></div><p>
See also:
<a class="link" href="BFont.html#BFont_SetEncoding" title="SetEncoding() , Encoding()"><code class="methodname">BFont::SetEncoding()</code></a>,
"<a class="xref" href="TheInterfaceKit_Character_Encoding.html" title="Character Encoding">Character Encoding</a>" section of the The Interface Kit chapter
</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="find_instantiation_func"></a>find_instantiation_func()</h3></div></div></div><a id="id1283914" class="indexterm"></a><p>
Declared in: <code class="filename">support/Archivable.h</code>
</p><div class="synopsisgroup">
<code class="methodsynopsis c"><span class="type">instantiation_func </span><span class="methodname">find_instantiation_func</span>(<span class="methodparam"><span class="modifier">const </span><span class="type">char* </span><span class="parameter">className</span></span>);</code>
<code class="methodsynopsis c"><span class="type">instantiation_func </span><span class="methodname">find_instantiation_func</span>(<span class="methodparam"><span class="type"><a class="link" href="BMessage.html" title="BMessage"><code class="classname">BMessage</code></a>* </span><span class="parameter">archive</span></span>);</code>
</div><p>
Returns a pointer to the
<a class="link" href="BArchivable.html#BArchivable_Instantiate" title="Instantiate()"><code class="methodname">Instantiate()</code></a>
function that can create instances
of the <code class="parameter">className</code> class, or <code class="constant">NULL</code> if the function can't be found. If passed
a <a class="link" href="BMessage.html" title="BMessage"><code class="classname">BMessage</code></a>
archive, <code class="function">find_instantiation_func()</code> gets the name of the class
from a <code class="constant">B_STRING_TYPE</code> field called "class" in the
<a class="link" href="BMessage.html" title="BMessage"><code class="classname">BMessage</code></a>.
</p><p>
The <span class="type">instantiation_func</span> type is defined as follows:
</p><pre class="programlisting example cpp"><code class="classname">BArchivable</code>* (*<code class="function">instantiation_func</code>) (<code class="classname">BMessage</code> *)</pre><p>
In other words, the function has the same syntax as the
<a class="link" href="BArchivable.html#BArchivable_Instantiate" title="Instantiate()"><code class="methodname">Instantiate()</code></a>
function declared in the
<a class="link" href="BArchivable.html" title="BArchivable"><code class="classname">BArchivable</code></a>
class and replicated in derived classes (with class-specific return values).
</p><p>
The function that's returned can be called like any C function; you don't
need the class name or another object of the class. For example:
</p><pre class="programlisting example cpp"><span class="type">instantiation_func</span> <code class="varname">func</code>;
if ( <code class="varname">func</code> = <code class="function">find_instantiation_func</code>(<code class="varname">arhiveMessage</code>) ) {
<code class="classname">BArchivable</code>* <code class="varname">object</code> = <code class="varname">func</code>(<code class="varname">archiveMessage</code>);
}</pre><p>
<code class="function">instantiate_object()</code> will do this work for you.
</p><p>
See also:
<a class="link" href="BArchivable.html#BArchivable_Instantiate" title="Instantiate()"><code class="methodname">Instantiate()</code></a>,
<a class="link" href="TheSupportKit_Functions.html#instantiate_object" title="instantiate_object()"><code class="function">instantiate_object()</code></a>
</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="instantiate_object"></a>instantiate_object()</h3></div></div></div><a id="id1284163" class="indexterm"></a><p>
Declared in: <code class="filename">support/Archivable.h</code>
</p><code class="methodsynopsis cpp"><span class="type"><a class="link" href="BArchivable.html" title="BArchivable"><code class="classname">BArchivable</code></a>* </span><span class="methodname">instantiate_object</span>(<span class="methodparam"><span class="type"><a class="link" href="BMessage.html" title="BMessage"><code class="classname">BMessage</code></a>* </span><span class="parameter">archive</span></span>);</code><p>
Creates and returns a new instance of an archived object, or returns <code class="constant">NULL</code>
if the object can't be constructed. The object is created by calling the
<a class="link" href="BArchivable.html#BArchivable_Instantiate" title="Instantiate()"><code class="methodname">Instantiate()</code></a>
function of…
</p><div class="orderedlist"><ol><li><p>
…the class that was last added to the "class" field (an array of
class names) of the archive
<a class="link" href="BMessage.html" title="BMessage"><code class="classname">BMessage</code></a>.
This will be the "most derived" class in the array.
</p></li><li><p>
If the named class isn't recognized by the app (or doesn't define
<a class="link" href="BArchivable.html#BArchivable_Instantiate" title="Instantiate()"><code class="methodname">Instantiate()</code></a>),
the function tries to load the add-on that's identified
(by signature) in archive's <code class="varname">add_on</code> field. This add-on should contain
the code for the class.
</p></li><li><p>
If the add-on method doesn't work, <code class="function">instantiate_object()</code> tries the
next class in the "class" array, and so works its way up the class
hierarchy.
</p></li><li><p>
If the appropriate class is never found, the function returns <code class="constant">NULL</code>.
</p></li></ol></div><p>
When successful, <code class="function">instantiate_object()</code> returns the object that
<code class="methodname">Instantiate()</code> created, but typed to the base
<a class="link" href="BArchivable.html" title="BArchivable"><code class="classname">BArchivable</code></a> class. The
<code class="function">cast_as()</code> macro can type it to a the proper class.
</p><pre class="programlisting example cpp"><code class="classname">BArchivable</code>* <code class="varname">base</code> = <code class="function">instantiate_object</code>(<code class="varname">archive</code>);
if ( <code class="varname">base</code> ) {
<code class="classname">TheClass</code>* <code class="varname">object</code> = <code class="function">cast_as</code>(<code class="varname">base</code>, <code class="classname">TheClass</code>);
if ( <code class="varname">object</code> ) {
. . .
}
}</pre></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="swap_data"></a><a id="is_type_swapped"></a>
swap_data(), is_type_swapped()</h3></div></div></div><a id="id1284379" class="indexterm"></a><a id="id1284386" class="indexterm"></a><p>
Declared in: <code class="filename">support/ByteSwap.h</code>
</p><code class="methodsynopsis c"><span class="type">status_t </span><span class="methodname">swap_data</span>(<span class="methodparam"><span class="type">type_code </span><span class="parameter">type</span></span>,<br />                   <span class="methodparam"><span class="type">void* </span><span class="parameter">data</span></span>,<br />                   <span class="methodparam"><span class="type">size_t </span><span class="parameter">length</span></span>,<br />                   <span class="methodparam"><span class="type">swap_action </span><span class="parameter">action</span></span>);</code><code class="methodsynopsis c"><span class="type">bool </span><span class="methodname">is_type_swapped</span>(<span class="methodparam"><span class="type">type_code </span><span class="parameter">type</span></span>);</code><p>
<code class="function">swap_data</code> is a general byte swapping function, converting data of type
type and converting its endianness according to action (defined in
"<a class="xref" href="TheSupportKit_Constants.html#Constants_Byte_Swapping" title="Byte Swapping Constants">
Byte Swapping Constants</a>").
The length field can be used to specify an array of
items to be converted. For example, you can convert an array of
<a class="link" href="BMessenger.html" title="BMessenger"><code class="classname">BMessenger</code></a>s
from little endian to the host endianness:
</p><pre class="programlisting example cpp"><code class="classname">BMessenger</code> <code class="varname">messengers</code>[10];
...
<code class="function">swap_data</code>(<code class="constant">B_MESSENGER_TYPE</code>, <code class="varname">messengers</code>, 10*sizeof(<code class="classname">BMessenger</code>)
<code class="constant">B_SWAP_LENDIAN_TO_HOST</code>);</pre><p>
The function can swap most data types with type constants defined in
<code class="filename">support/TypeConstants.h</code>.
It returns <code class="constant">B_OK</code> on success and <code class="constant">B_BAD_VALUE</code>
on failure.
</p><p>
<code class="function">is_type_swapped()</code> takes a type code and determines whether or not it has
been swapped. This only works for types defined in
<code class="filename">support/TypeConstants.h</code>.
It returns <code class="constant">true</code> if the type code is in the
host's native endianness and <code class="constant">false</code> otherwise.
</p><p>
See also:
"<a class="xref" href="TheSupportKit_Constants.html#Constants_Byte_Swapping" title="Byte Swapping Constants">
Byte Swapping Constants</a>"
</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="Macros_min"></a><a id="Macros_max_c"></a>
<a id="Macros_min_c"></a>
<a id="Macros_max"></a>
min(), max(), min_c(), max_c()</h3></div></div></div><p>
Declared in: <code class="filename">support/SupportDefs.h</code>
</p><code class="methodsynopsis c"><span class="methodname">min</span>(<span class="methodparam"><span class="parameter">a</span></span>,<br />    <span class="methodparam"><span class="parameter">b</span></span>);</code><code class="methodsynopsis cpp"><span class="methodname">min_c</span>(<span class="methodparam"><span class="parameter">a</span></span>,<br />      <span class="methodparam"><span class="parameter">b</span></span>);</code><code class="methodsynopsis c"><span class="methodname">max</span>(<span class="methodparam"><span class="parameter">a</span></span>,<br />    <span class="methodparam"><span class="parameter">b</span></span>);</code><code class="methodsynopsis cpp"><span class="methodname">max_c</span>(<span class="methodparam"><span class="parameter">a</span></span>,<br />      <span class="methodparam"><span class="parameter">b</span></span>);</code><p>
These macros compare two integers or floating-point numbers.
<code class="methodname">min()</code> and
<code class="methodname">min_c()</code> return the lesser of the two (or b if they're equal);
<code class="methodname">max()</code> and
<code class="methodname">max_c()</code> return the greater of the two (or a if they're equal).
<code class="methodname">min()</code> and
<code class="methodname">max()</code> can only be used in straight C programs.
<code class="methodname">min_c()</code> and
<code class="methodname">max_c()</code> are
defined for C and C++.
</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="validate_instantiation"></a>validate_instantiation()</h3></div></div></div><a id="id1284761" class="indexterm"></a><code class="methodsynopsis cpp"><span class="type">bool </span><span class="methodname">validate_instantiation</span>(<span class="methodparam"><span class="type">BMessage* </span><span class="parameter">archive</span></span>,<br />                            <span class="methodparam"><span class="modifier">const </span><span class="type">char* </span><span class="parameter">className</span></span>);</code><p>
Declared in: <code class="filename">support/Archivable.h</code>
</p><p>
Returns <code class="constant">true</code> if the <code class="parameter">archive</code>
<a class="link" href="BMessage.html" title="BMessage"><code class="classname">BMessage</code></a> contains data for an object
belonging to the <code class="parameter">className</code> class, and <code class="constant">false</code> if not. The determination is
made by looking for the class name in a "class" array in the archive. If
the class name appears anywhere in the array, this function returns <code class="constant">true</code>.
If not, it returns <code class="constant">false</code>.
</p></div></div><div id="footer"><hr /><div id="footerT">Prev: <a href="BString.html">BString</a>  Up: <a href="TheSupportKit.html">The Support Kit</a>  Next: <a href="TheSupportKit_Constants.html">Constants</a> </div><div id="footerB"><div id="footerBL"><a href="BString.html" title="BString"><img src="./images/navigation/prev.png" alt="Prev" /></a> <a href="TheSupportKit.html" title="The Support Kit"><img src="./images/navigation/up.png" alt="Up" /></a> <a href="TheSupportKit_Constants.html" title="Constants"><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>
Reference in New Issue View Git Blame Copy Permalink