removed former haiku_book and headersampler tool
git-svn-id: file:///srv/svn/repos/haiku/haiku/trunk@22445 a95241bf-73f2-0310-859d-f6bbb57e9c96
This commit is contained in:
Jérôme Duval
@@ -2,6 +2,5 @@ SubDir HAIKU_TOP src documentation ;
|
||||
|
||||
SEARCH on <src!documentation>license.xml = [ FDirName $(HAIKU_TOP) src documentation ] ;
|
||||
|
||||
SubInclude HAIKU_TOP src documentation haiku_book ;
|
||||
SubInclude HAIKU_TOP src documentation uiguidelines ;
|
||||
SubInclude HAIKU_TOP src documentation shell_tools ;
|
||||
|
||||
@@ -1,85 +0,0 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
||||
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
|
||||
<!--
|
||||
Things that need fixing should be marked as such with either "TODO"
|
||||
or "FIXME".
|
||||
|
||||
-->
|
||||
|
||||
<!ENTITY appkit SYSTEM "appkit.xml">
|
||||
<!ENTITY devicekit SYSTEM "devicekit.xml">
|
||||
<!ENTITY gamekit SYSTEM "gamekit.xml">
|
||||
<!ENTITY interfacekit SYSTEM "interfacekit.xml">
|
||||
<!ENTITY kernelkit SYSTEM "kernelkit.xml">
|
||||
<!ENTITY mailkit SYSTEM "mailkit.xml">
|
||||
<!ENTITY mediakit SYSTEM "mediakit.xml">
|
||||
<!ENTITY midikit SYSTEM "midikit.xml">
|
||||
<!ENTITY networkkit SYSTEM "networkkit.xml">
|
||||
<!ENTITY openglkit SYSTEM "openglkit.xml">
|
||||
<!ENTITY storagekit SYSTEM "storagekit.xml">
|
||||
<!ENTITY supportkit SYSTEM "supportkit.xml">
|
||||
<!ENTITY translationkit SYSTEM "translationkit.xml">
|
||||
|
||||
<!-- license -->
|
||||
<!ENTITY license SYSTEM "../license.xml">
|
||||
|
||||
<!-- Text Macros -->
|
||||
<!ENTITY haikuorg '<ulink url="http://www.haiku-os.org/">Haiku</ulink>'>
|
||||
<!ENTITY haiku "Haiku">
|
||||
|
||||
]>
|
||||
|
||||
<book id="index">
|
||||
<bookinfo>
|
||||
<title>Haiku Book</title>
|
||||
<pubdate>2005-05-16</pubdate>
|
||||
<authorgroup>
|
||||
<author>
|
||||
<firstname>Jerome</firstname>
|
||||
<surname>Duval</surname>
|
||||
</author>
|
||||
<author>
|
||||
<firstname>Matthijs</firstname>
|
||||
<surname>Hollemans</surname>
|
||||
</author>
|
||||
</authorgroup>
|
||||
|
||||
<abstract>
|
||||
<para>
|
||||
This guide is the documentation for the C and C++ API of &haiku;.
|
||||
</para>
|
||||
</abstract>
|
||||
|
||||
<revhistory>
|
||||
<revision>
|
||||
<revnumber>1.00</revnumber>
|
||||
<date>2005-05-16</date>
|
||||
<authorinitials>kor</authorinitials>
|
||||
<revremark>Initial version.</revremark>
|
||||
</revision>
|
||||
</revhistory>
|
||||
</bookinfo>
|
||||
|
||||
|
||||
<!-- Chapters
|
||||
-->
|
||||
&appkit;
|
||||
&devicekit;
|
||||
&gamekit;
|
||||
&interfacekit;
|
||||
&kernelkit;
|
||||
&mailkit;
|
||||
&mediakit;
|
||||
&midikit;
|
||||
&networkkit;
|
||||
&openglkit;
|
||||
&storagekit;
|
||||
&supportkit;
|
||||
&translationkit;
|
||||
|
||||
<!--
|
||||
The License
|
||||
-->
|
||||
&license;
|
||||
</book>
|
||||
@@ -1,106 +0,0 @@
|
||||
SubDir HAIKU_TOP src documentation haiku_book ;
|
||||
|
||||
SetSubDirSupportedPlatformsBeOSCompatible ;
|
||||
|
||||
Doc2HTML
|
||||
Haiku_Book.xml
|
||||
: index.html
|
||||
: [ FDirName $(HAIKU_TOP) src documentation docbook-xsl html chunk.xsl ]
|
||||
: Haiku_Book
|
||||
:
|
||||
: -stringparam use.id.as.filename 1 -stringparam language cpp -stringparam chunk.section.depth 2
|
||||
;
|
||||
|
||||
Doc2HTML
|
||||
howto.xml
|
||||
: Haiku_Book_Howto.html
|
||||
: [ FDirName $(HAIKU_TOP) src documentation docbook-xsl html chunk.xsl ]
|
||||
: Haiku_Book_Howto
|
||||
:
|
||||
: -stringparam language cpp
|
||||
;
|
||||
|
||||
# Single most ugly string manipulation ever ...
|
||||
rule FRelGristFiles
|
||||
{
|
||||
#local targets = $(1) ;
|
||||
|
||||
#local fallbackgrist = $(2:J=!) ;
|
||||
#local gristval = $(SOURCE_GRIST:E=$(fallbackgrist)) ;
|
||||
|
||||
#local sourcegrist = $(targets:G=gristval) ;
|
||||
#return $(targets:G=$(gristval)) ;
|
||||
|
||||
return $(<:G=$(SOURCE_GRIST:E)$(>:J=!)) ;
|
||||
}
|
||||
|
||||
local chapter_files = appkit.xml
|
||||
devicekit.xml
|
||||
gamekit.xml
|
||||
interfacekit.xml
|
||||
kernelkit.xml
|
||||
mailkit.xml
|
||||
mediakit.xml
|
||||
midikit.xml
|
||||
networkkit.xml
|
||||
openglkit.xml
|
||||
storagekit.xml
|
||||
supportkit.xml
|
||||
translationkit.xml ;
|
||||
|
||||
Includes [ FGristFiles Haiku_Book.xml ]
|
||||
: [ FGristFiles $(chapter_files) ] <src!documentation>license.xml ;
|
||||
SEARCH on [ FGristFiles $(chapter_files) ] = [ FDirName $(SUBDIR) ] ;
|
||||
|
||||
local app_files = intro.xml messaging.xml scripting.xml Application.xml ;
|
||||
Includes [ FGristFiles appkit.xml ] : [ FRelGristFiles $(app_files) : app ] ;
|
||||
SEARCH on [ FRelGristFiles $(app_files) : app ] = [ FDirName $(SUBDIR) app ] ;
|
||||
|
||||
local device_files = intro.xml Joystick.xml SerialPort.xml ;
|
||||
Includes [ FGristFiles devicekit.xml ] : [ FRelGristFiles $(device_files) : device ] ;
|
||||
SEARCH on [ FRelGristFiles $(device_files) : device ] = [ FDirName $(SUBDIR) device ] ;
|
||||
|
||||
local game_files = intro.xml ;
|
||||
Includes [ FGristFiles gamekit.xml ] : [ FRelGristFiles $(game_files) : game ] ;
|
||||
SEARCH on [ FRelGristFiles $(game_files) : game ] = [ FDirName $(SUBDIR) game ] ;
|
||||
|
||||
local interface_files = intro.xml ;
|
||||
Includes [ FGristFiles interfacekit.xml ] : [ FRelGristFiles $(interface_files) : interface ] ;
|
||||
SEARCH on [ FRelGristFiles $(interface_files) : interface ] = [ FDirName $(SUBDIR) interface ] ;
|
||||
|
||||
local kern_files = intro.xml threads.xml ports.xml sems.xml ;
|
||||
Includes [ FGristFiles kernelkit.xml ] : [ FRelGristFiles $(kern_files) : kernel ] ;
|
||||
SEARCH on [ FRelGristFiles $(kern_files) : kernel ] = [ FDirName $(SUBDIR) kernel ] ;
|
||||
|
||||
local mail_files = intro.xml ;
|
||||
Includes [ FGristFiles mailkit.xml ] : [ FRelGristFiles $(mail_files) : mail ] ;
|
||||
SEARCH on [ FRelGristFiles $(mail_files) : mail ] = [ FDirName $(SUBDIR) mail ] ;
|
||||
|
||||
local media_files = intro.xml ;
|
||||
Includes [ FGristFiles mediakit.xml ] : [ FRelGristFiles $(media_files) : media ] ;
|
||||
SEARCH on [ FRelGristFiles $(media_files) : media ] = [ FDirName $(SUBDIR) media ] ;
|
||||
|
||||
local midi_files = intro.xml midi2.xml midi2consumer.xml midi2endpoint.xml midi2localproducer.xml midi2roster.xml
|
||||
midi1.xml midi2api.xml midi2defs.xml midi2localconsumer.xml midi2producer.xml ;
|
||||
Includes [ FGristFiles midikit.xml ] : [ FRelGristFiles $(midi_files) : midi ] ;
|
||||
SEARCH on [ FRelGristFiles $(midi_files) : midi ] = [ FDirName $(SUBDIR) midi ] ;
|
||||
|
||||
local network_files = intro.xml ;
|
||||
Includes [ FGristFiles networkkit.xml ] : [ FRelGristFiles $(network_files) : network ] ;
|
||||
SEARCH on [ FRelGristFiles $(network_files) : network ] = [ FDirName $(SUBDIR) network ] ;
|
||||
|
||||
local opengl_files = intro.xml ;
|
||||
Includes [ FGristFiles openglkit.xml ] : [ FRelGristFiles $(opengl_files) : opengl ] ;
|
||||
SEARCH on [ FRelGristFiles $(opengl_files) : opengl ] = [ FDirName $(SUBDIR) opengl ] ;
|
||||
|
||||
local storage_files = intro.xml ;
|
||||
Includes [ FGristFiles storagekit.xml ] : [ FRelGristFiles $(storage_files) : storage ] ;
|
||||
SEARCH on [ FRelGristFiles $(storage_files) : storage ] = [ FDirName $(SUBDIR) storage ] ;
|
||||
|
||||
local support_files = intro.xml ;
|
||||
Includes [ FGristFiles supportkit.xml ] : [ FRelGristFiles $(support_files) : support ] ;
|
||||
SEARCH on [ FRelGristFiles $(support_files) : support ] = [ FDirName $(SUBDIR) support ] ;
|
||||
|
||||
local translation_files = intro.xml ;
|
||||
Includes [ FGristFiles translationkit.xml ] : [ FRelGristFiles $(translation_files) : translation ] ;
|
||||
SEARCH on [ FRelGristFiles $(translation_files) : translation ] = [ FDirName $(SUBDIR) translation ] ;
|
||||
@@ -1,148 +0,0 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
||||
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
|
||||
|
||||
]>
|
||||
|
||||
<sect1 id="app-Application">
|
||||
<title>BApplication</title>
|
||||
|
||||
<bridgehead renderas="sect2">Member Functions</bridgehead>
|
||||
|
||||
<sect3 id="bapplication_bapplication">
|
||||
<title>BApplication()</title>
|
||||
<methodsynopsis><methodname>BApplication</methodname><methodparam><modifier>const</modifier><type>char *</type><parameter>signature</parameter></methodparam></methodsynopsis>
|
||||
<methodsynopsis><methodname>BApplication</methodname><methodparam><modifier>const</modifier><type>char *</type><parameter>signature</parameter></methodparam><methodparam><type>status_t *</type><parameter>error</parameter></methodparam></methodsynopsis>
|
||||
<methodsynopsis><methodname>BApplication</methodname><methodparam><type>BMessage *</type><parameter>data</parameter></methodparam></methodsynopsis>
|
||||
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bapplication_tildebapplication">
|
||||
<title>~BApplication()</title>
|
||||
<methodsynopsis><modifier>virtual</modifier><methodname>~BApplication</methodname><void/></methodsynopsis>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bapplication_instanciate">
|
||||
<title>Instanciate()</title>
|
||||
<methodsynopsis><modifier>static</modifier><type>BArchivable *</type><methodname>Instantiate</methodname><methodparam><type>BMessage *</type><parameter>data</parameter></methodparam></methodsynopsis>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bapplication_archive">
|
||||
<title>Archive()</title>
|
||||
<methodsynopsis><modifier>virtual</modifier><type>status_t</type><methodname>Archive</methodname><methodparam><type>BMessage *</type><parameter>data</parameter></methodparam><methodparam><type>bool</type><parameter>deep</parameter><initializer>true</initializer></methodparam><modifier>const</modifier></methodsynopsis>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bapplication_initcheck">
|
||||
<title>InitCheck()</title>
|
||||
<methodsynopsis><type>status_t</type><methodname>InitCheck</methodname><void/><modifier>const</modifier></methodsynopsis>
|
||||
</sect3>
|
||||
<sect3 id="bapplication_run">
|
||||
<title>Run()</title>
|
||||
<methodsynopsis><modifier>virtual</modifier><type>thread_id</type><methodname>Run</methodname><void/></methodsynopsis>
|
||||
</sect3>
|
||||
<sect3 id="bapplication_quit">
|
||||
<title>Quit()</title>
|
||||
<methodsynopsis><modifier>virtual</modifier><void/><methodname>Quit</methodname><void/></methodsynopsis>
|
||||
</sect3>
|
||||
<sect3 id="bapplication_quitrequested">
|
||||
<title>QuitRequested()</title>
|
||||
<methodsynopsis><modifier>virtual</modifier><type>bool</type><methodname>QuitRequested</methodname><void/></methodsynopsis>
|
||||
</sect3>
|
||||
<sect3 id="bapplication_pulse">
|
||||
<title>Pulse()</title>
|
||||
<methodsynopsis><modifier>virtual</modifier><void/><methodname>Pulse</methodname><void/></methodsynopsis>
|
||||
</sect3>
|
||||
<sect3 id="bapplication_readytorun">
|
||||
<title>ReadyToRun()</title>
|
||||
<methodsynopsis><modifier>virtual</modifier><void/><methodname>ReadyToRun</methodname><void/></methodsynopsis>
|
||||
</sect3>
|
||||
<sect3 id="bapplication_messagereceived">
|
||||
<title>MessageReceived()</title>
|
||||
<methodsynopsis><modifier>virtual</modifier><void/><methodname>MessageReceived</methodname><methodparam><type>BMessage *</type><parameter>msg</parameter></methodparam></methodsynopsis>
|
||||
</sect3>
|
||||
<sect3 id="bapplication_argvreceived">
|
||||
<title>ArgvReceived()</title>
|
||||
<methodsynopsis><modifier>virtual</modifier><void/><methodname>ArgvReceived</methodname><methodparam><type>int32</type><parameter>argc</parameter></methodparam><methodparam><type>char * *</type><parameter>argv</parameter></methodparam></methodsynopsis>
|
||||
</sect3>
|
||||
<sect3 id="bapplication_appactivated">
|
||||
<title>AppActivated()</title>
|
||||
<methodsynopsis><modifier>virtual</modifier><void/><methodname>AppActivated</methodname><methodparam><type>bool</type><parameter>active</parameter></methodparam></methodsynopsis>
|
||||
</sect3>
|
||||
<sect3 id="bapplication_refsreceived">
|
||||
<title>RefsReceived()</title>
|
||||
<methodsynopsis><modifier>virtual</modifier><void/><methodname>RefsReceived</methodname><methodparam><type>BMessage *</type><parameter>message</parameter></methodparam></methodsynopsis>
|
||||
</sect3>
|
||||
<sect3 id="bapplication_aboutrequested">
|
||||
<title>AboutRequested()</title>
|
||||
<methodsynopsis><modifier>virtual</modifier><void/><methodname>AboutRequested</methodname><void/></methodsynopsis>
|
||||
</sect3>
|
||||
<sect3 id="bapplication_resolvespecifier">
|
||||
<title>ResolveSpecifier()</title>
|
||||
<methodsynopsis><modifier>virtual</modifier><type>BHandler *</type><methodname>ResolveSpecifier</methodname><methodparam><type>BMessage *</type><parameter>msg</parameter></methodparam><methodparam><type>int32</type><parameter>index</parameter></methodparam><methodparam><type>BMessage *</type><parameter>specifier</parameter></methodparam><methodparam><type>int32</type><parameter>form</parameter></methodparam><methodparam><modifier>const</modifier><type>char *</type><parameter>property</parameter></methodparam></methodsynopsis>
|
||||
</sect3>
|
||||
<sect3 id="bapplication_showcursor">
|
||||
<title>ShowCursor()</title>
|
||||
<methodsynopsis><void/><methodname>ShowCursor</methodname><void/></methodsynopsis>
|
||||
</sect3>
|
||||
<sect3 id="bapplication_hidecursor">
|
||||
<title>HideCursor()</title>
|
||||
<methodsynopsis><void/><methodname>HideCursor</methodname><void/></methodsynopsis>
|
||||
</sect3>
|
||||
<sect3 id="bapplication_obscurecursor">
|
||||
<title>ObscureCursor()</title>
|
||||
<methodsynopsis><void/><methodname>ObscureCursor</methodname><void/></methodsynopsis>
|
||||
</sect3>
|
||||
<sect3 id="bapplication_iscursorhidden">
|
||||
<title>IsCursorHidden()</title>
|
||||
<methodsynopsis><type>bool</type><methodname>IsCursorHidden</methodname><void/><modifier>const</modifier></methodsynopsis>
|
||||
</sect3>
|
||||
<sect3 id="bapplication_setcursor">
|
||||
<title>SetCursor</title>
|
||||
<methodsynopsis><void/><methodname>SetCursor</methodname><methodparam><modifier>const</modifier><type>void *</type><parameter>cursor</parameter></methodparam></methodsynopsis>
|
||||
<methodsynopsis><void/><methodname>SetCursor</methodname><methodparam><modifier>const</modifier><type>BCursor *</type><parameter>cursor</parameter></methodparam><methodparam><type>bool</type><parameter>sync</parameter><initializer>true</initializer></methodparam></methodsynopsis>
|
||||
</sect3>
|
||||
<sect3 id="bapplication_countwindows">
|
||||
<title>CountWindows()</title>
|
||||
<methodsynopsis><type>int32</type><methodname>CountWindows</methodname><void/><modifier>const</modifier></methodsynopsis>
|
||||
</sect3>
|
||||
<sect3 id="bapplication_windowat">
|
||||
<title>WindowAt()</title>
|
||||
<methodsynopsis><type>BWindow *</type><methodname>WindowAt</methodname><methodparam><type>int32</type><parameter>index</parameter></methodparam><modifier>const</modifier></methodsynopsis>
|
||||
</sect3>
|
||||
<sect3 id="bapplication_countloopers">
|
||||
<title>CountLoopers()</title>
|
||||
<methodsynopsis><type>int32</type><methodname>CountLoopers</methodname><void/><modifier>const</modifier></methodsynopsis>
|
||||
</sect3>
|
||||
<sect3 id="bapplication_looperat">
|
||||
<title>LooperAt()</title>
|
||||
<methodsynopsis><type>BLooper *</type><methodname>LooperAt</methodname><methodparam><type>int32</type><parameter>index</parameter></methodparam><modifier>const</modifier></methodsynopsis>
|
||||
</sect3>
|
||||
<sect3 id="bapplication_islaunching">
|
||||
<title>IsLaunching</title>
|
||||
<methodsynopsis><type>bool</type><methodname>IsLaunching</methodname><void/><modifier>const</modifier></methodsynopsis>
|
||||
</sect3>
|
||||
<sect3 id="bapplication_getappinfo">
|
||||
<title>GetAppInfo()</title>
|
||||
<methodsynopsis><type>status_t</type><methodname>GetAppInfo</methodname><methodparam><type>app_info *</type><parameter>info</parameter></methodparam><modifier>const</modifier></methodsynopsis>
|
||||
</sect3>
|
||||
<sect3 id="bapplication_appresources">
|
||||
<title>AppResources()</title>
|
||||
<methodsynopsis><modifier>static</modifier><type>BResources *</type><methodname>AppResources</methodname><void/></methodsynopsis>
|
||||
</sect3>
|
||||
<sect3 id="bapplication_dispatchmessage">
|
||||
<title>DispatchMessage()</title>
|
||||
<methodsynopsis><modifier>virtual</modifier><void/><methodname>DispatchMessage</methodname><methodparam><type>BMessage *</type><parameter>message</parameter></methodparam><methodparam><type>BHandler *</type><parameter>handler</parameter></methodparam></methodsynopsis>
|
||||
</sect3>
|
||||
<sect3 id="bapplication_setpulserate">
|
||||
<title>SetPulseRate()</title>
|
||||
<methodsynopsis><void/><methodname>SetPulseRate</methodname><methodparam><type>bigtime_t</type><parameter>rate</parameter></methodparam></methodsynopsis>
|
||||
</sect3>
|
||||
<sect3 id="bapplication_getsupportedsuites">
|
||||
<title>GetSupportedSuites()</title>
|
||||
<methodsynopsis><modifier>virtual</modifier><type>status_t</type><methodname>GetSupportedSuites</methodname><methodparam><type>BMessage *</type><parameter>data</parameter></methodparam></methodsynopsis>
|
||||
</sect3>
|
||||
<sect3 id="bapplication_perform">
|
||||
<title>Perform()</title>
|
||||
<methodsynopsis><modifier>virtual</modifier><type>status_t</type><methodname>Perform</methodname><methodparam><type>perform_code</type><parameter>d</parameter></methodparam><methodparam><type>void *</type><parameter>arg</parameter></methodparam></methodsynopsis>
|
||||
</sect3>
|
||||
</sect1>
|
||||
@@ -1,25 +0,0 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
||||
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
|
||||
|
||||
]>
|
||||
|
||||
<sect1 id="app-intro">
|
||||
<title>Introduction</title>
|
||||
|
||||
<para>
|
||||
Application Kit is about classes needed to interact with other applications or the screen. Information about it is available in several topics :
|
||||
</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem><para>
|
||||
<xref linkend="app-messaging"/> helps to send and receive data from other processes.
|
||||
</para></listitem>
|
||||
<listitem><para>
|
||||
<xref linkend="app-scripting"/> helps to operate by program on other applications.
|
||||
</para></listitem>
|
||||
<listitem><para>
|
||||
<xref linkend="app-Application"/> describes an application object. Each application creates one instance to register with the system.
|
||||
</para></listitem>
|
||||
</itemizedlist>
|
||||
</sect1>
|
||||
@@ -1,10 +0,0 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
||||
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
|
||||
|
||||
]>
|
||||
|
||||
<sect1 id="app-messaging">
|
||||
<title>Messaging</title>
|
||||
|
||||
</sect1>
|
||||
@@ -1,10 +0,0 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
||||
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
|
||||
|
||||
]>
|
||||
|
||||
<sect1 id="app-scripting">
|
||||
<title>Scripting</title>
|
||||
|
||||
</sect1>
|
||||
@@ -1,11 +0,0 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
|
||||
<chapter id="st-appkit">
|
||||
<title>The Application Kit</title>
|
||||
|
||||
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="app/intro.xml" />
|
||||
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="app/messaging.xml" />
|
||||
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="app/scripting.xml" />
|
||||
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="app/Application.xml" />
|
||||
</chapter>
|
||||
|
||||
@@ -1,9 +0,0 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
||||
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
|
||||
|
||||
]>
|
||||
|
||||
<sect1 id="device-Joystick">
|
||||
<title>BJoystick</title>
|
||||
</sect1>
|
||||
@@ -1,9 +0,0 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
||||
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
|
||||
|
||||
]>
|
||||
|
||||
<sect1 id="device-SerialPort">
|
||||
<title>BSerialPort</title>
|
||||
</sect1>
|
||||
@@ -1,23 +0,0 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
||||
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
|
||||
|
||||
]>
|
||||
|
||||
<sect1 id="device-intro">
|
||||
<title>Introduction</title>
|
||||
|
||||
<para>
|
||||
The <emphasis>Device Kit</emphasis> provides a collection of classes which provide a programmer a convenient interface with hardware devices attached to the computer. These classes free one from dealing with extraneous details, instead focusing on the device itself.
|
||||
</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem><para>
|
||||
<xref linkend="device-SerialPort"/> facilitates usage of an RS-232 port.
|
||||
</para></listitem>
|
||||
<listitem><para>
|
||||
<xref linkend="device-Joystick"/> allows polling of any joystick or gamepad.
|
||||
</para></listitem>
|
||||
</itemizedlist>
|
||||
</sect1>
|
||||
|
||||
@@ -1,11 +0,0 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
|
||||
<chapter id="st-devicekit">
|
||||
<title>The Device Kit</title>
|
||||
|
||||
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="device/intro.xml" />
|
||||
|
||||
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="device/Joystick.xml" />
|
||||
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="device/SerialPort.xml" />
|
||||
</chapter>
|
||||
|
||||
@@ -1,17 +0,0 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
||||
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
|
||||
|
||||
]>
|
||||
|
||||
<sect1 id="game-intro">
|
||||
<title>Introduction</title>
|
||||
|
||||
<para>
|
||||
The <emphasis>Game Kit</emphasis> consists of a number of classes which provide:
|
||||
<itemizedlist>
|
||||
<listitem>Fast, but low level, 2D graphics functionality</listitem>
|
||||
<listitem>Convenient sound effect loading, management and playback</listitem>
|
||||
</itemizedlist>
|
||||
</para>
|
||||
</sect1>
|
||||
@@ -1,7 +0,0 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
|
||||
<chapter id="st-gamekit">
|
||||
<title>The Game Kit</title>
|
||||
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="game/intro.xml" />
|
||||
</chapter>
|
||||
|
||||
@@ -1,738 +0,0 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
||||
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
|
||||
|
||||
<!-- license -->
|
||||
<!ENTITY license SYSTEM "../license.xml">
|
||||
]>
|
||||
|
||||
<book id="developerdochowto">
|
||||
<bookinfo>
|
||||
<title>Developer Documentation Writing Howto</title>
|
||||
<pubdate>2005-10-26</pubdate>
|
||||
<authorgroup>
|
||||
<author>
|
||||
<firstname>Niels</firstname>
|
||||
<surname>Reedijk</surname>
|
||||
</author>
|
||||
</authorgroup>
|
||||
|
||||
<abstract>
|
||||
<para>
|
||||
This guide is for Haiku Developers that need to write developer documentation.
|
||||
</para>
|
||||
</abstract>
|
||||
|
||||
<revhistory>
|
||||
<revision>
|
||||
<revnumber>1</revnumber>
|
||||
<date>2005-12-23</date>
|
||||
<authorinitials>nielx</authorinitials>
|
||||
<revremark>First section about documenting classes on review.</revremark>
|
||||
</revision>
|
||||
</revhistory>
|
||||
</bookinfo>
|
||||
|
||||
<chapter id="introduction">
|
||||
<title>Introduction</title>
|
||||
|
||||
<para>
|
||||
The Haiku project maintains application programming interface (from now on
|
||||
<acronym>API</acronym>) documentation for developers that want to write and port
|
||||
applications on the platform. The project strives to create and maintain a uniform and
|
||||
clear book that describes the <acronym>API</acronym>, named the Haiku Book.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The tool to help structure and format the Haiku Book is Docbook. Docbook is originally
|
||||
a <acronym>SGML</acronym>-based text that was developed for separating structure
|
||||
and formatting in the age of digital publication. Docbook is basically a document type
|
||||
definition (from now on <acronym>DTD</acronym>) that provides a standard that can be
|
||||
used to generate a whole slew of output formats. The Haiku project chose this format
|
||||
so that the documentation can be transformed into several output formats without any
|
||||
effort. Furthermore, the format is is widely used and understood, and is structured by
|
||||
the well-known <acronym>XML</acronym> standard.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
This document is written to prescribe a set of conventions so that the Haiku Book will
|
||||
become a coherent whole. It also serves as a manual for those that are unfamiliar with
|
||||
docbook, who will probably at times feel 'lost'. However, beginners using this manual
|
||||
when documenting their classes, you will be able to generate proper docbook and create
|
||||
a structure that fits in with the rest. Since the <acronym>DTD</acronym> contains over
|
||||
three hundred elements, this document also selects which elements are used in our
|
||||
documentation. Thus, this manual is also helpful to those more familiar with docbook.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
At the moment there is only one section finished. <xref linkend="classes"/>
|
||||
</para>
|
||||
</chapter>
|
||||
|
||||
<chapter id="classes">
|
||||
<title>Documenting Classes</title>
|
||||
|
||||
<para>
|
||||
This chapter will outline all the formal docbook structure for documenting classes,
|
||||
as well as give hints on the content of the documentation.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
If you are documenting a class that hasn't been documented before, please read
|
||||
the <link linkend="newclass">section on documenting a new class</link>. If you are
|
||||
working on an existing class, you can proceed to the
|
||||
<link linkend="formalformatting">formal formatting</link>.
|
||||
</para>
|
||||
|
||||
<sect1 id="newclass">
|
||||
<title>Documenting a new class</title>
|
||||
|
||||
<para>
|
||||
This section describes the rules on where to place the documentation of a new
|
||||
class. It discusses
|
||||
the place in the file hierchy, and how to hook it into the existing documentation.
|
||||
Please read through this desciption carefully if you are adding a new class. For
|
||||
those that are merely modifying classes that already exist, you can skip this
|
||||
section.
|
||||
</para>
|
||||
|
||||
<sect2 id="filelocation">
|
||||
<title>Where do I place my file?</title>
|
||||
|
||||
<para>
|
||||
When writing the documentation for a new class, you will create a new file.
|
||||
This file needs to be placed in the hierchy in the subversion repository, that
|
||||
is located at <filename>src/documentation/haiku_book/</filename>. This
|
||||
directory contains a set of subdirectories that correspond with the class
|
||||
division the Haiku project uses. You place your file in the subdirectory that
|
||||
corresponds to the kit the class belongs to.
|
||||
</para>
|
||||
</sect2>
|
||||
|
||||
<sect2 id="filename">
|
||||
<title>How do I name my file?</title>
|
||||
|
||||
<para>
|
||||
The naming of the file, consistent with header and source naming, consists
|
||||
of the class name <emphasis>without</emphasis> the <classname>B</classname>
|
||||
prefix and with the <filename>xml</filename> extension. For example, the
|
||||
<classname>BList</classname> class would have the <filename>List.xml</filename>
|
||||
documentation file.
|
||||
</para>
|
||||
</sect2>
|
||||
|
||||
<sect2 id="filecontents">
|
||||
<title>What should be the initial contents of the file?</title>
|
||||
|
||||
<para>
|
||||
The minimal required content for the file is a line that is required by the
|
||||
<acronym>XML</acronym> standard. Furthermore, you'll have to "open" a new
|
||||
section (and close it), and you'll have to add a title. For example, the
|
||||
<classname>BList</classname> class has the following bare minimum:
|
||||
</para>
|
||||
|
||||
<programlisting>
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
|
||||
<sect2 id="blist">
|
||||
<title>BList</title>
|
||||
</sect2>
|
||||
</programlisting>
|
||||
|
||||
<para>
|
||||
Please note the following. The <literal>sect2</literal> element, like other
|
||||
<literal>sect</literal> elements, has the element <literal>id</literal>. This
|
||||
id contains the classname in lowercase, including the B-prefix.
|
||||
For notes on the XML formatting style, please see elsewhere in this document.
|
||||
</para>
|
||||
</sect2>
|
||||
|
||||
<sect2 id="hookinfile">
|
||||
<title>How do I hook in the file into the generated documentation?</title>
|
||||
|
||||
<para>
|
||||
If you have created the file and put it in the subdirectory that's appropriate
|
||||
for the kit it belongs to, it's time to hook it into the generated documents.
|
||||
The way to do this is by opening the <filename>api.xml</filename> file that's
|
||||
located in that same subdirectory. Hooking in is a two-step process. First, you
|
||||
create an entity in the doctype declaration that refers to the content of the
|
||||
file that describes the class, secondly you refer to that entity in the body of
|
||||
the document.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The first step involves adding a line at the top of the file in the doctype
|
||||
declaration. In clase of <classname>BList</classname>, the following has been
|
||||
done.
|
||||
</para>
|
||||
|
||||
<programlisting>
|
||||
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
||||
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
|
||||
|
||||
<!ENTITY list SYSTEM "List.xml">
|
||||
|
||||
]>
|
||||
</programlisting>
|
||||
|
||||
<para>
|
||||
The line with the <literal>ENTITY</literal> in it, is the one that you need to
|
||||
recreate for your own file. There are things you need to adapt. First of all,
|
||||
you need to adapt <literal>list</literal> to reflect the name of the file in
|
||||
lowercase, since entities are lowercase by convention. Secondly, you need
|
||||
to change the filename it refers too. Please make sure you've got the case
|
||||
right!
|
||||
</para>
|
||||
|
||||
<note><para>
|
||||
Please note that the inclusions are by convention in alphabetical order. So
|
||||
make sure the new line is at the proper spot.
|
||||
</para></note>
|
||||
|
||||
<para>
|
||||
The second step is calling the entity in the body. For example in the support
|
||||
kit:
|
||||
</para>
|
||||
|
||||
<programlisting>
|
||||
<sect1 id="supportapi">
|
||||
<title>Support Kit API</title>
|
||||
|
||||
&list;
|
||||
</sect1>
|
||||
</programlisting>
|
||||
|
||||
<para>
|
||||
The main body of the <filename>api.xml</filename> file consists of a list of
|
||||
entities. You place your entity in the list (on a new line). Please remember
|
||||
that entities are refered to by prefixing the name with
|
||||
<quote><literal>&</literal></quote> and postfixing
|
||||
<quote><literal>;</literal></quote>. Please note that this also should be in
|
||||
alphabetical order by convention.
|
||||
</para>
|
||||
</sect2>
|
||||
</sect1>
|
||||
|
||||
<sect1 id="formalformatting">
|
||||
<title>Formal formatting of a class</title>
|
||||
|
||||
<para>
|
||||
Thersomee are formal requirements for class documentation to be consistent with
|
||||
the rest of the <acronym>API</acronym> documentation. This section will explain in
|
||||
what order things should be documented, what the formal structural markup
|
||||
for methods is and what sections are required.
|
||||
</para>
|
||||
|
||||
<sect2 id="structure">
|
||||
<title>What elements should be in class documentation?</title>
|
||||
|
||||
<para>
|
||||
This sections describes the order in which things should be described. It
|
||||
will touch a little bit of the docbook elements used in the larger structure. It
|
||||
will not describe how you should structure the individual methods. That's for
|
||||
<link linkend="methodsynopsis">the next section</link>.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
We can distinguish roughly three parts. First of all, we've got the class
|
||||
summary. This includes a formal block with useful information. Secondly,
|
||||
we document the constructors and destructors. Thirdly, we describe the static
|
||||
members that the class might have. Then we describe
|
||||
the member functions. Finally we describe the operators that are overloaded.
|
||||
Note that any section can be left out if it's not applicable. For example, the
|
||||
<classname>BList</classname> class doesn't have actual overloaded operators,
|
||||
thus that section is not in the actual documentation. The following example
|
||||
gives a rough outline of the <classname>BList</classname> documentation.
|
||||
</para>
|
||||
|
||||
<programlisting>
|
||||
<sect2 id="blist">
|
||||
<title>BList</title>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem><para><emphasis>Derived from:</emphasis> none</para></listitem>
|
||||
<listitem><para><emphasis>Declared in:</emphasis> <filename>os/support/List.h</filename></para></listitem>
|
||||
<listitem><para><emphasis>Library:</emphasis> <filename>libbe.so</filename></para></listitem>
|
||||
</itemizedlist>
|
||||
|
||||
... summary comes here ...
|
||||
|
||||
<bridgehead renderas="sect2">Constructors and Destructors</bridgehead>
|
||||
|
||||
... constructors come here ...
|
||||
|
||||
<bridgehead renderas="sect2">Static Functions</bridgehead>
|
||||
|
||||
... member functions come here ...
|
||||
|
||||
<bridgehead renderas="sect2">Member Functions</bridgehead>
|
||||
|
||||
... member functions come here ...
|
||||
|
||||
<bridgehead renderas="sect2">Operators</bridgehead>
|
||||
|
||||
... operators would come here ...
|
||||
</programlisting>
|
||||
|
||||
<sect3 id="summary">
|
||||
<title>Class Summary</title>
|
||||
|
||||
<para>
|
||||
The first part of the class description is the summary. In the example
|
||||
above it runs from <literal><title>BList</title></literal> to
|
||||
the first <literal><bridgehead></literal>. There is an obligatory
|
||||
<literal><itemizedlist></literal>. This list contains three elements:
|
||||
the class it is derived from, the location it is declared in and the
|
||||
library you need to link to.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Note that every item in the <literal><itemizedlist></literal> begins
|
||||
with <literal><listitem></literal>, which also happens to be the
|
||||
final tags. The item is started with the tag <literal><para></literal>.
|
||||
The labels to every piece of data is put inside an
|
||||
<literal><emphasis></literal> block, including the semicolon! There's
|
||||
a space between the endtag and the actual value.
|
||||
</para>
|
||||
|
||||
<orderedlist>
|
||||
<listitem><para>
|
||||
The value of the first item, <quote>Derived from:</quote>, is either a
|
||||
classname, or <literal>none</literal>. If it is a class, make sure you link
|
||||
to it using the entity available. For example, if your class is derived
|
||||
from <classname>BList</classname>, use <literal>&BList;</literal>.
|
||||
This generates a nice crosslink within the documentation.
|
||||
</para></listitem>
|
||||
|
||||
<listitem><para>
|
||||
The value of the second item, <quote>Declared in:</quote>, is wrapped
|
||||
inside a <literal><filename></literal> tag. You refer to the path
|
||||
relative to the <filename>header</filename> subdirectory in the Haiku
|
||||
source tree.
|
||||
</para></listitem>
|
||||
|
||||
<listitem><para>
|
||||
The value of the third item, <quote>Library:</quote>, is also wrapped
|
||||
inside a <literal><filename></literal> tag. Stating the name of the
|
||||
library suffices. The example can be found in <filename>libbe.so</filename>.
|
||||
</para></listitem>
|
||||
</orderedlist>
|
||||
|
||||
<para>
|
||||
After that obligatory block, you can write a summary. This section won't
|
||||
go into details of what good summaries contain (and what they don't).
|
||||
Please remember to wrap every paragraph into a set of
|
||||
<literal><para></literal> tags. Also note that if you link to methods
|
||||
inside your class, that you use the appopriate entities. So if I want to
|
||||
link to <methodname>AddItem</methodname> of my class, I use
|
||||
<literal>&BList_AddItem;</literal>.
|
||||
</para>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="constructordescription">
|
||||
<title>Constructor and Destructor</title>
|
||||
|
||||
<para>
|
||||
The second part focusses on constructors and the
|
||||
destructor, and the third on the actual members. The second section starts
|
||||
after the first <literal><bridgehead></literal> with the label
|
||||
<quote>Constructors and Destructors</quote>. See for example the
|
||||
<classname>BList</classname> constructors and destructors:
|
||||
</para>
|
||||
|
||||
<programlisting>
|
||||
<bridgehead renderas="sect2">Constructors and Destructors</bridgehead>
|
||||
|
||||
<sect3 id="blist_constructor">
|
||||
<title>BList()</title>
|
||||
|
||||
<constructorsynopsis>
|
||||
<methodname>BList</methodname>
|
||||
<methodparam><type>int32</type><parameter>count</parameter><initializer>20</initializer></methodparam>
|
||||
</constructorsynopsis>
|
||||
|
||||
<constructorsynopsis>
|
||||
<methodname>BList</methodname>
|
||||
<methodparam><modifier>const</modifier><type>BList &amp;</type><parameter>list</parameter></methodparam>
|
||||
</constructorsynopsis>
|
||||
|
||||
... Description of the constructors here ...
|
||||
</sect3>
|
||||
|
||||
<sect3 id="blist_destructor">
|
||||
<title>~BList()</title>
|
||||
|
||||
<destructorsynopsis>
|
||||
<methodname>~BList</methodname>
|
||||
</destructorsynopsis>
|
||||
|
||||
... Description of the destructor here ...
|
||||
</sect3>
|
||||
</programlisting>
|
||||
|
||||
<para>
|
||||
First of all, the <literal><bridgehead></literal> element is an
|
||||
element that instructs the stylesheet that transforms the docbook to an
|
||||
output format to place a header in the same style as the header of the
|
||||
section (hence the <literal>renderas="sect2"</literal> attribute). Because
|
||||
of hierchial reasons, we don't actually want to start a new section. A
|
||||
similar <literal><bridgehead></literal> is used as the second header
|
||||
for the member functions.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
As you might notice, the <classname>BList</classname> has two constructors
|
||||
and one destructor. The constructors are bundled together in the
|
||||
<literal><sect3></literal> element with the id
|
||||
<literal>blist_constructor</literal>. Like every other id, this one is
|
||||
lowercase. The label must be the full classname in lowercase, an
|
||||
underscore and the word <literal>constructor</literal>. The destructor
|
||||
section is built up in a similar way. The title is the name of the method,
|
||||
without any of it's arguments. So in case of the constructor, it is
|
||||
BList().
|
||||
</para>
|
||||
|
||||
<para>
|
||||
As you can see, there is a normal constructor and a copy constructor. The
|
||||
rule is that the copy constructor should always be places last. If you have
|
||||
overloaded constructors, the order is somewhat at will, but please take as
|
||||
guiding principle that it's most logical to order the constructors in order of
|
||||
the amount of parameters (so from most complex to simpler). Feel free to
|
||||
drop this order if your argument in the description or the synopsis requires
|
||||
another order of constructors.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The actual descriptions of the constructors are embedded in a
|
||||
<literal><constructorsynopsis></literal> element. The destructor
|
||||
is embedded in a <literal><destructorsynopsis></literal> element.
|
||||
These are special variations of the <literal><methodsynopsis></literal>
|
||||
construction, for they don't require a return type. They do follow the rest of
|
||||
the rules of the <literal><methodsynopsis></literal> construction.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
For a more detailed description about the
|
||||
<literal><methodsynopsis></literal> construction, see
|
||||
<xref linkend="methodsynopsis"/>. Some guiding lines on writing descriptions
|
||||
will occur in a later section, but please note that you should wrap them in
|
||||
<literal><para></literal> tags.
|
||||
</para>
|
||||
</sect3>
|
||||
<sect3 id="methoddescriptions">
|
||||
<title>Static and Member documentation</title>
|
||||
|
||||
<para>
|
||||
Static documentation starts under the second
|
||||
<literal><bridgehead></literal> with the label
|
||||
<quote>Static Functions</quote>. The member functions start under
|
||||
<quote>Member Functions</quote>. These <literal><bridgehead></literal>
|
||||
have the same properties as the one the one used with the constructors.
|
||||
Note that either section can be left out if they are not applicable.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
In order to illustrate some of the principles, here's a piece of the
|
||||
documentation for the <classname>BList</classname> class:
|
||||
</para>
|
||||
|
||||
<programlisting>
|
||||
<bridgehead renderas="sect2">Member Functions</bridgehead>
|
||||
<sect3 id="blist_additem">
|
||||
<title>AddItem()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>bool</type><methodname>AddItem</methodname>
|
||||
<methodparam><type>void *</type><parameter>item</parameter></methodparam>
|
||||
<methodparam><type>int32</type><parameter>index</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>bool</type><methodname>AddItem</methodname>
|
||||
<methodparam><type>void *</type><parameter>item</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
|
||||
... Here comes documentation for this (or these) method(s)...
|
||||
</sect3>
|
||||
|
||||
<sect3 id="blist_countitems">
|
||||
<title>CountItems()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>int32</type><methodname>CountItems</methodname><modifier>const</modifier>
|
||||
</methodsynopsis>
|
||||
|
||||
... Here comes documentation for this (or these) method(s)...
|
||||
</sect3>
|
||||
|
||||
<sect3 id="blist_removeitem">
|
||||
<title>RemoveItem()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>bool</type><methodname>RemoveItem</methodname>
|
||||
<methodparam><type>void *</type><parameter>item</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>void *</type><methodname>RemoveItem</methodname>
|
||||
<methodparam><type>int32</type><parameter>index</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>bool</type><methodname>RemoveItems</methodname>
|
||||
<methodparam><type>int32</type><parameter>index</parameter></methodparam>
|
||||
<methodparam><type>int32</type><parameter>count</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
|
||||
... Here comes documentation for this (or these) method(s)...
|
||||
</sect3>
|
||||
|
||||
<sect3 id="blist_removeitems">
|
||||
<title>RemoveItems()</title>
|
||||
|
||||
<para>See &BList_RemoveItem;</para>
|
||||
</sect3>
|
||||
</programlisting>
|
||||
|
||||
<para>
|
||||
The first thing that's important is that every distinct method has it's own
|
||||
<literal><sect3></literal>. The <literal>id</literal> attribute is build up of the
|
||||
lowercase full classname, an underscore and the name of the method, also in
|
||||
lowercase. There are no braces present. The title of the section is the
|
||||
name of the method with proper casing, followed by closed braces (without a
|
||||
space before or between them). Note that all the sections are ordered
|
||||
alphabetically.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Let's take the <methodname>CountItems()</methodname> method as an example.
|
||||
We notice that the prototype of the function is encapsulated in a
|
||||
<literal><methodsynopsis></literal> construction. This construction
|
||||
is discussed in more detail in <xref linkend="methodsynopsis"/>. If a
|
||||
method is overloaded, like the <methodname>AddItem()</methodname>
|
||||
method, both the prototypes are given.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Important is the fact that multiple methods can be grouped together. For
|
||||
instance, the documentation for the <methodname>RemoveItems()</methodname>
|
||||
method is included in the documentation of the singular
|
||||
<methodname>RemoveItem()</methodname>. Thus that prototype is listed in
|
||||
that location. Please note that it still is obligatory to create a separate
|
||||
section for <methodname>RemoveItems()</methodname>, as you can see in the
|
||||
example. You don't have to put anything in that section, besides the title
|
||||
and one <literal><para></literal> with the contents <quote>See</quote>
|
||||
and the entity that refers to the method where it is documented.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
If you group different methods together, the rule is that they should be in
|
||||
alphabetical order. If you have overloaded method, take the guideline that
|
||||
they should be reverse ordered in complexity (complex first, simple later).
|
||||
The guideline is that this should be done by the amount of parameters, but
|
||||
if your method or documentation would be clearer by another order, you are
|
||||
allowed to order them as you like.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
After the method synopsis is done, you add the documentation. This section
|
||||
doesn't discuss the guidelines for writing good documentation. Please refer
|
||||
to another section for that. Do remember that you need to wrap it between
|
||||
<literal><para></literal> elements.
|
||||
</para>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="operators">
|
||||
<title>Operators</title>
|
||||
|
||||
<para>
|
||||
Operator overloading is quite common in the Haiku <acronym>API</acronym>
|
||||
and as such it should be documented. The original Be Book gave operators
|
||||
a special treatment, and we've decided to reproduce it in the Haiku Book as
|
||||
well. As noted before, if there are any overloaded operators, they are placed
|
||||
under a special <literal>bridgehead</literal> with the label Operators. In
|
||||
essence, operators aren't so different from methods in the sense that
|
||||
they both contain a <literal>methodsynopsis</literal> and a description,
|
||||
but there are some oddities you need to be aware of. See the example
|
||||
from the <classname>BString</classname> class:
|
||||
</para>
|
||||
|
||||
<programlisting>
|
||||
<bridgehead renderas="sect2">Operators</bridgehead>
|
||||
<sect3 id="bstring_operator_assignment">
|
||||
<title>= (assignment)</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>BString &amp;</type><methodname>operator=</methodname>
|
||||
<methodparam><modifier>const</modifier><type>BString &amp;</type><parameter>string</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>BString &amp;</type><methodname>operator=</methodname>
|
||||
<methodparam><modifier>const</modifier><type>char *</type><parameter>string</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
</programlisting>
|
||||
|
||||
<para>
|
||||
The first thing to note is how the <literal>id</literal> in the
|
||||
<literal>sect3</literal> tag is built up. It starts with the lowercase
|
||||
classname, an underscore, the word <literal>operator</literal> an
|
||||
underscore, and a short description of what the operator does. Later this
|
||||
section I'll try to present some standard operator descriptions which you
|
||||
should follow as much as possible.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The next thing is the title. The title is built up of the operator (here the
|
||||
=), and a description of what it does, lowercase in parenthesis.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Last thing of note in this example is that the <literal>methodname</literal>
|
||||
is quite literally the name of the method in the header file. This wraps up
|
||||
the conventions we use for individual overloaded operators.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
More interesting is the order of the operators. The following list shows
|
||||
the order and the common descriptions of the overloaded operators.
|
||||
</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem><para>= (assignment)</para></listitem>
|
||||
<listitem><para>+= (append)</para></listitem>
|
||||
<listitem><para><< (stream; formatted append)</para></listitem>
|
||||
<listitem><para>[] (indexing)</para></listitem>
|
||||
<listitem><para> ==, !=, <, >, <=, >= (comparison)</para></listitem>
|
||||
</itemizedlist>
|
||||
|
||||
<note><para>
|
||||
This list is far from complete. As more classes are documented, more
|
||||
possiblities will be described. Do try to combine the comparison operators
|
||||
into one block: they share the same features. Also, if your description
|
||||
contains a space, substitute it for an underscore in the <literal>id</literal>
|
||||
parameter of the <literal>sect3</literal> tag.
|
||||
</para></note>
|
||||
</sect3>
|
||||
</sect2>
|
||||
|
||||
<sect2 id="methodsynopsis">
|
||||
<title>How do I write a proper methodsynopsis?</title>
|
||||
|
||||
<para>
|
||||
Docbook provides several tools for properly documenting methods. It is
|
||||
important that you use the correct markup, to create a uniform format. A
|
||||
synopsis lives inside a <literal>methodsynopsis</literal> block. So open
|
||||
and close the block and follow the following list of instructions step by step
|
||||
to document the methods properly.
|
||||
</para>
|
||||
|
||||
<orderedlist>
|
||||
<listitem><para>
|
||||
Open the block with <literal><methodsynopsis></literal>. Then put in
|
||||
a newline and jump in one tab.
|
||||
</para></listitem>
|
||||
|
||||
<listitem><para>
|
||||
If the method has a <emphasis>modifier</emphasis>, the first element of
|
||||
the line is this modifier. Modifiers are <literal>virtual</literal>,
|
||||
<literal>inline</literal> and <literal>static</literal>. Enclose the modifier
|
||||
in a <literal>modifier</literal> block.
|
||||
</para></listitem>
|
||||
|
||||
<listitem><para>
|
||||
For the return type, there are two options.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
In case the method doesn't return a value, please use the tag
|
||||
<literal><void/></literal>. Note the trailing slash!
|
||||
</para>
|
||||
|
||||
<para>
|
||||
In case of a return type, please enclose the return type in a
|
||||
<literal>type</literal> block. Note that if you've got
|
||||
<literal>const BList *</literal> as a return type, that complete segment
|
||||
is the return type. So the <literal>const</literal> is also considered a
|
||||
part of the return type!
|
||||
</para></listitem>
|
||||
|
||||
<listitem><para>
|
||||
The name of the method is next, which should be enclosed in a
|
||||
<literal>methodname</literal> block. Use the proper
|
||||
capitalisation. Note that you don't need to include the trailing
|
||||
parenthesis. The stylesheet will do this when it processes the block.
|
||||
</para></listitem>
|
||||
|
||||
<listitem><para>
|
||||
If the method has arguments, put every argument on a new line. Put the line
|
||||
between <literal><methodparam></literal> tags.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
If the argument has a modifier, use the <literal>modifier</literal>
|
||||
tag. Modifiers are <literal>const</literal> and <literal>mutable</literal>.
|
||||
<emphasis>Notice that <literal>const</literal> is considered a modifier
|
||||
in arguments, as opposed to <literal>const</literal> in return
|
||||
values.</emphasis> The logic is that you may pass a non-const object
|
||||
in, and the modifier just tells you how the method is going to handle it, as
|
||||
opposed to the return value which always is the const object when it has
|
||||
that modifier.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Put the type of the argument between <literal>type</literal> tags. Note
|
||||
that if the argument is a pointer or a reference, that the asterix (*) and
|
||||
the ampersand (&) are included between the tags. Pay attention
|
||||
to the fact that <acronym>XML</acronym> requires your ampersand to be
|
||||
encoded like this: &amp;.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Enclose the the name of the parameter between <literal>parameter</literal>
|
||||
tags. Note that the name of the parameter is obligatory. Use the original
|
||||
name that is in the header file.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
If the argument has an initialiser, put the value between the
|
||||
<literal>initializer</literal> tags. Note that you should not put the = in
|
||||
front of it.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Don't forget to end each line with <literal></methodparam></literal>!
|
||||
</para></listitem>
|
||||
|
||||
<listitem><para>
|
||||
The last thing you need to be aware of is whether or not the method is
|
||||
modified by a trailing <literal>const</literal>, or if the method is a pure
|
||||
virtual. If so, you need to append either
|
||||
<literal><modifier>const</modifier></literal> or
|
||||
<literal><modifier>= 0</modifier></literal>. Please note the
|
||||
space between the <quote>=</quote> and the <quote>0</quote> in the
|
||||
syntax for the pure virtuals. The location of this modifier
|
||||
depends on whether or not the method has arguments. If it doesn't have
|
||||
any arguments, just append it to the single line you've written. If there are
|
||||
arguments, put this on a newline after the last argument.
|
||||
</para></listitem>
|
||||
|
||||
<listitem><para>
|
||||
And of course, the <literal><methodsynopsis></literal> ends with
|
||||
<literal>/<methodsynopsis></literal>.
|
||||
</para></listitem>
|
||||
</orderedlist>
|
||||
|
||||
<note><para>
|
||||
Please note that constructors and destructors have a slightly different syntax.
|
||||
Instead of the <literal><methodsynopsis></literal> tags, they are
|
||||
enclosed in the <literal><constructorsynopsis></literal> or
|
||||
<literal><destructorsynopsis></literal> tags. And they don't have return
|
||||
types. The rest of the rules that are described here are valid.
|
||||
</para></note>
|
||||
</sect2>
|
||||
</sect1>
|
||||
</chapter>
|
||||
|
||||
&license;
|
||||
</book>
|
||||
@@ -1,13 +0,0 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
||||
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
|
||||
|
||||
]>
|
||||
|
||||
<sect1 id="interface-intro">
|
||||
<title>Introduction</title>
|
||||
|
||||
<para>
|
||||
The <emphasis>Interface Kit</emphasis> is the core of the window drawing, clicking-dragging, typing, scrolling, GUI world of Haiku. Any application which wants to use any widget will use this set of classes to manage their windows and respond to user/system feedback.
|
||||
</para>
|
||||
</sect1>
|
||||
@@ -1,7 +0,0 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
|
||||
<chapter id="st-interfacekit">
|
||||
<title>The Interface Kit</title>
|
||||
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="interface/intro.xml" />
|
||||
</chapter>
|
||||
|
||||
@@ -1,25 +0,0 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
||||
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
|
||||
|
||||
]>
|
||||
|
||||
<sect1 id="kernel-intro">
|
||||
<title>Introduction</title>
|
||||
|
||||
<para>
|
||||
Kernel Kit is about classes needed to interact with the kernel. Information about it is available in several topics :
|
||||
</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem><para>
|
||||
<xref linkend="kern-threads"/> helps to perform tasks.
|
||||
</para></listitem>
|
||||
<listitem><para>
|
||||
<xref linkend="kern-ports"/> helps to communicate between threads.
|
||||
</para></listitem>
|
||||
<listitem><para>
|
||||
<xref linkend="kern-sems"/> helps to synchronize threads.
|
||||
</para></listitem>
|
||||
</itemizedlist>
|
||||
</sect1>
|
||||
@@ -1,10 +0,0 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
||||
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
|
||||
|
||||
]>
|
||||
|
||||
<sect1 id="kern-ports">
|
||||
<title>Ports</title>
|
||||
|
||||
</sect1>
|
||||
@@ -1,10 +0,0 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
||||
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
|
||||
|
||||
]>
|
||||
|
||||
<sect1 id="kern-sems">
|
||||
<title>Semaphores</title>
|
||||
|
||||
</sect1>
|
||||
@@ -1,10 +0,0 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
||||
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
|
||||
|
||||
]>
|
||||
|
||||
<sect1 id="kern-threads">
|
||||
<title>Threads</title>
|
||||
|
||||
</sect1>
|
||||
@@ -1,12 +0,0 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
|
||||
<chapter id="st-kernelkit">
|
||||
<title>The Kernel Kit</title>
|
||||
|
||||
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="kernel/intro.xml" />
|
||||
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="kernel/threads.xml" />
|
||||
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="kernel/ports.xml" />
|
||||
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="kernel/sems.xml" />
|
||||
|
||||
</chapter>
|
||||
|
||||
@@ -1,18 +0,0 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
||||
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
|
||||
|
||||
]>
|
||||
|
||||
<sect1 id="mail-intro">
|
||||
<title>Introduction</title>
|
||||
|
||||
<para> The <emphasis>Mail Kit</emphasis> encompasses all email activities on Haiku, providing means for, but not limited to:
|
||||
<itemizedlist>
|
||||
<listitem><para>Sending and receiving of email</para></listitem>
|
||||
<listitem><para>Interfacing for the manipulation of email messages and attachments</para></listitem>
|
||||
<listitem><para>Manipulating email account information</para></listitem>
|
||||
</itemizedlist>
|
||||
</para>
|
||||
</sect1>
|
||||
|
||||
@@ -1,8 +0,0 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
|
||||
<chapter id="st-mailkit">
|
||||
<title>The Mail Kit</title>
|
||||
|
||||
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="mail/intro.xml" />
|
||||
|
||||
</chapter>
|
||||
@@ -1,17 +0,0 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
||||
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
|
||||
|
||||
]>
|
||||
|
||||
<sect1 id="media-intro">
|
||||
<title>Introduction</title>
|
||||
|
||||
<para>
|
||||
The <emphasis>Media Kit</emphasis> controls the heart of the Haiku media playback, recording and transformation. It contains classes in two main areas:
|
||||
<itemizedlist>
|
||||
<listitem>Application: The consumption and production of media. Encoding, decoding and playback.</listitem>
|
||||
<listitem>Node: Direct manipulation of media nodes which process the media</listitem>
|
||||
</itemizedlist>
|
||||
</para>
|
||||
</sect1>
|
||||
@@ -1,8 +0,0 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
|
||||
<chapter id="st-mediakit">
|
||||
<title>The Media Kit</title>
|
||||
|
||||
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="media/intro.xml" />
|
||||
</chapter>
|
||||
|
||||
@@ -1,48 +0,0 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
||||
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
|
||||
|
||||
]>
|
||||
|
||||
<sect1 id="midi-intro">
|
||||
<title>Introduction</title>
|
||||
|
||||
<para>
|
||||
The Midi Kit is the API that implements support for generating, processing, and
|
||||
playing music in MIDI format. <ulink url="http://www.midi.org/">MIDI</ulink>, which
|
||||
stands for 'Musical Instrument Digital Interface', is a well-established
|
||||
standard for representing and communicating musical data.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The BeOS comes with two different, but compatible Midi Kits. This documentation
|
||||
focuses on the "new" Midi Kit, or midi2 as we like to call it, that was
|
||||
introduced with BeOS R5. The old kit, which we'll refer to as midi1, is more
|
||||
complete than the new kit, but less powerful.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Both kits let you create so-called MIDI endpoints, but the endpoints from midi1
|
||||
cannot be shared between different applications. The midi2 kit solves that
|
||||
problem, but unlike midi1 it does not include a General MIDI softsynth, nor
|
||||
does it have a facility for reading and playing Standard MIDI Files. Don't
|
||||
worry: both kits are compatible and you can mix-and-match them in your
|
||||
applications.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The main differences between the two kits:
|
||||
<itemizedlist>
|
||||
<listitem><para>Instead of one <classname>BMidi</classname> object that both produces and consumes events, we have
|
||||
<classname>BMidiProducer</classname> and <classname>BMidiConsumer</classname>.</para></listitem>
|
||||
<listitem><para>Applications are capable of sharing MIDI producers and consumers with other
|
||||
applications via the centralized Midi Roster.</para></listitem>
|
||||
<listitem><para>Physical MIDI ports are now sharable without apps "stealing" events from each
|
||||
other.</para></listitem>
|
||||
<listitem><para>Applications can now send/receive raw MIDI byte streams (useful if an
|
||||
application has its own MIDI parser/engine).</para></listitem>
|
||||
<listitem><para>Channels are numbered 0..15, not 1..16</para></listitem>
|
||||
<listitem><para>Timing is now specified in microseconds instead of milliseconds.</para></listitem>
|
||||
</itemizedlist>
|
||||
</para>
|
||||
</sect1>
|
||||
@@ -1,66 +0,0 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
||||
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
|
||||
|
||||
]>
|
||||
|
||||
<sect1 id="midi1">
|
||||
<title>The Old Midi 1 Kit</title>
|
||||
<para>
|
||||
The old Midi Kit, or midi1 for short, goes all the way back to DR8, when the
|
||||
BeOS only ran on BeBoxen. Fortunately for us, it is pretty well documented:
|
||||
<itemizedlist>
|
||||
<listitem><para><ulink url="http://bang.dhs.org/be/bebook/The%20Midi%20Kit/index.html">Midi
|
||||
Kit chapter in the online Be Book</ulink></para></listitem>
|
||||
<listitem><para><ulink url="http://web.archive.org/web/20010618100542/www-classic.be.com/developers/developer_library/midi_kit.html">Midi
|
||||
Kit section of the old Be Developer Library</ulink></para></listitem>
|
||||
<listitem><para>Be Newsletter Volume 1, Issue 49 - Introduces the MIDI synth</para></listitem>
|
||||
<listitem><para>Be Newsletter Volume 1, Issue 52 - Follow-up on issue 49</para></listitem>
|
||||
<listitem><para>Be Newsletter Volume 1, Issue 91 - How to use BSynth</para></listitem>
|
||||
<listitem><para>Be Newsletter Volume 1, Issue 102 - Axe sample code</para></listitem>
|
||||
<listitem><para>Be Newsletter Volume 1, Issue 104 - How to use BMidiPort</para></listitem>
|
||||
<listitem><para>Be Newsletter Volume 2, Issue 23 - EdMidi sample code</para></listitem>
|
||||
<listitem><para>Be Newsletter Volume 2, Issue 37 - How to use the MIDI synth</para></listitem>
|
||||
<listitem><para>Be Newsletter Volume 3, Issue 37 - Whistle sample code</para></listitem>
|
||||
</itemizedlist></para>
|
||||
|
||||
<para>
|
||||
To summarize, there are four basic MIDI classes:
|
||||
<itemizedlist>
|
||||
<listitem><para><classname>BMidi</classname> is the base class for most other classes from the Midi Kit.</para></listitem>
|
||||
<listitem><para><classname>BMidiPort</classname> can talk to a MIDI hardware port.</para></listitem>
|
||||
<listitem><para><classname>BMidiStore</classname> can read, write, and perform Standard MIDI files.</para></listitem>
|
||||
<listitem><para><classname>BMidiText</classname> is a debugging aid that dumps MIDI messages to <function>stdout</function></para></listitem>
|
||||
</itemizedlist>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The following classes let you use the Midi Kit's General MIDI synthesizer:
|
||||
<itemizedlist>
|
||||
<listitem><para><classname>BSynth</classname> controls the synthesizer.</para></listitem>
|
||||
<listitem><para><classname>BMidiSynth</classname> connects a <classname>BMidi</classname> object to the synth.</para></listitem>
|
||||
<listitem><para><classname>BMidiSynthFile</classname> connects a MIDI file to the synth</para></listitem>
|
||||
<listitem><para><classname>BSamples</classname> lets you access the synth's sound data stream</para></listitem>
|
||||
</itemizedlist></para>
|
||||
|
||||
<para>
|
||||
To make MIDI data stream through your application, you create a "network" of
|
||||
BMidi-derived objects that send and receive MIDI messages.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The old Midi Kit is slowly fading into obscurity. You may want to use the
|
||||
<link linkend="midi2">MIDI 2 Kit</link> instead. Also note that the Haiku implementation
|
||||
of the kit sometimes behaves differently than the one from BeOS R5 or what
|
||||
the BeBook says, but usually for the better ;-)
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Especially the synth classes are not completely functional, but enough to
|
||||
play back General MIDI tunes. They should be backwards compatible with the
|
||||
majority of BeOS MIDI applications. Not all methods of BSynth, BMidiSynth,
|
||||
and BMidiSynthFile are implemented because some of them are rather obscure.
|
||||
BSamples is a complete no-op; in other words, with the Haiku Midi Kit
|
||||
you cannot push waveform data into the output stream of the softsynth.
|
||||
</para>
|
||||
</sect1>
|
||||
@@ -1,362 +0,0 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
||||
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
|
||||
|
||||
]>
|
||||
|
||||
<sect1 id="midi2"><title>The Midi 2 Kit</title>
|
||||
|
||||
<sect2 id="concepts">
|
||||
<title>Concepts</title>
|
||||
|
||||
<para>
|
||||
A brief overview of the elements that comprise the Midi Kit:
|
||||
<itemizedlist>
|
||||
<listitem><para><emphasis>Endpoints</emphasis>. This is what the Midi Kit is all about: sending MIDI messages
|
||||
between endpoints. An endpoint is like a MIDI In or MIDI Out socket on your
|
||||
equipment; it either receives information or it sends information. Endpoints
|
||||
that send MIDI events are called \b producers; the endpoints that receive those
|
||||
events are called \b consumers. An endpoint that is created by your own
|
||||
application is called \b local; endpoints from other applications are \b
|
||||
remote. You can access remote endpoints using \b proxies.</para></listitem>
|
||||
|
||||
<listitem><para><emphasis>Filters</emphasis>. A filter is an object that has a consumer and a producer
|
||||
endpoint. It reads incoming events from its consumer, performs some operation,
|
||||
and tells its producer to send out the results. In its current form, the Midi
|
||||
Kit doesn't provide any special facilities for writing filters.</para></listitem>
|
||||
|
||||
<listitem><para><emphasis>Midi Roster</emphasis>. The roster is the list of all published producers and
|
||||
consumers. By publishing an endpoint, you allow other applications to talk to
|
||||
it. You are not required to publish your endpoints, in which case only your own
|
||||
application can use them.</para></listitem>
|
||||
|
||||
<listitem><para><emphasis>Midi Server</emphasis>. The Midi Server does the behind-the-scenes work. It
|
||||
manages the roster, it connects endpoints, it makes sure that endpoints can
|
||||
communicate, and so on. The Midi Server is started automatically when BeOS
|
||||
boots, and you never have to deal with it directly. Just remember that it runs
|
||||
the show.</para></listitem>
|
||||
|
||||
<listitem><para><filename>libmidi</filename>. The BMidi* classes live inside two shared libraries: <filename>libmidi.so</filename>
|
||||
and <filename>libmidi2.so</filename>. If you write an application that uses old Midi Kit, you must
|
||||
link it to <filename>libmidi.so</filename>. Applications that use the new Midi Kit must link to
|
||||
<filename>libmidi2.so</filename>. If you want to mix-and-match both kits, you should also link to
|
||||
both libraries.</para></listitem>
|
||||
</itemizedlist>
|
||||
</para>
|
||||
|
||||
<figure id="midi2concepts"><title>The concepts captured in an image</title>
|
||||
<mediaobject>
|
||||
<imageobject>
|
||||
<imagedata fileref="midi/midi2concepts.png"/>
|
||||
</imageobject>
|
||||
<textobject><phrase>An overview of the MIDI kit.</phrase></textobject>
|
||||
</mediaobject>
|
||||
</figure>
|
||||
</sect2>
|
||||
|
||||
<sect2 id="midi2media">
|
||||
<title>Midi Kit != Media Kit</title>
|
||||
|
||||
<para>
|
||||
Be chose not to integrate the Midi Kit into the Media Kit as another media
|
||||
type, mainly because MIDI doesn't require any of the format negotiation that
|
||||
other media types need. Although the two kits look similar -- both have a
|
||||
"roster" for finding or registering "consumers" and "producers" -- there are
|
||||
some very important differences.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The first and most important point to note is that BMidiConsumer and
|
||||
BMidiProducer in the Midi Kit are NOT directly analogous to BBufferConsumer and
|
||||
BBufferProducer in the Media Kit! In the Media Kit, consumers and producers are
|
||||
the data consuming and producing properties of a media node. A filter in the
|
||||
Media Kit, therefore, inherits from both BBufferConsumer and BBufferProducer,
|
||||
and implements their virtual member functions to do its work.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
In the Midi Kit, consumers and producers act as endpoints of MIDI data
|
||||
connections, much as media_source and media_destination do in the Media Kit.
|
||||
Thus, a MIDI filter does not derive from BMidiConsumer and BMidiProducer;
|
||||
instead, it contains BMidiConsumer and BMidiProducer objects for each of its
|
||||
distinct endpoints that connect to other MIDI objects. The Midi Kit does not
|
||||
allow the use of multiple virtual inheritance, so you can't create an object
|
||||
that's both a BMidiConsumer and a BMidiProducer.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
This also contrasts with the old Midi Kit's conception of a BMidi object, which
|
||||
stood for an object that both received and sent MIDI data. In the new Midi Kit,
|
||||
the endpoints of MIDI connections are all that matters. What lies between the
|
||||
endpoints, i.e., how a MIDI filter is actually structured, is entirely at your
|
||||
discretion.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Also, rather than use token structs like media_node to make connections via the
|
||||
MediaRoster, the new kit makes the connections directly via the BMidiProducer
|
||||
object.
|
||||
</para>
|
||||
</sect2>
|
||||
|
||||
<sect2 id="midi2remotelocal">
|
||||
<title>Remote and local objects</title>
|
||||
|
||||
<para>
|
||||
The Midi Kit makes a distinction between remote and local MIDI objects. You can
|
||||
only create local MIDI endpoints, which derive from either BMidiLocalConsumer
|
||||
or BMidiLocalProducer. Remote endpoints are endpoints that live in other
|
||||
applications, and you access them through BMidiRoster.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
BMidiRoster only gives you access to BMidiEndpoints, BMidiConsumers, and
|
||||
BMidiProducers. When you want to talk to remote MIDI objects, you do so through
|
||||
the proxy objects that BMidiRoster provides. Unlike BMidiLocalConsumer and
|
||||
BMidiLocalProducer, these classes do not provide a lot of functions. That is
|
||||
intentional. In order to hide the details of communication with MIDI endpoints
|
||||
in other applications, the Midi Kit must hide the details of how a particular
|
||||
endpoint is implemented.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
So, what can you do with remote objects? Only what BMidiConsumer,
|
||||
BMidiProducer, and BMidiEndpoint will let you do. You can connect objects, get
|
||||
the properties of these objects -- and that's about it.
|
||||
</para>
|
||||
</sect2>
|
||||
|
||||
<sect2 id="midi2lifespan">
|
||||
<title>Creating and Destroying Objects</title>
|
||||
|
||||
<para>
|
||||
The constructors and destructors of most midi2 classes are private, which mean
|
||||
you cannot directly create them using the C++ <function>new</function> operator, on the
|
||||
stack, or as globals. Nor can you <function>delete</function> them. Instead, these
|
||||
objects are obtained through BMidiRoster. The only two exceptions to this rule
|
||||
are BMidiLocalConsumer and BMidiLocalProducer. These two objects may be
|
||||
directly created and subclassed by developers.
|
||||
</para>
|
||||
</sect2>
|
||||
|
||||
<sect2 id="midi2refcount">
|
||||
<title>Reference Counting</title>
|
||||
|
||||
<para>
|
||||
Each MIDI endpoint has a reference count associated with it, so that the Midi
|
||||
Roster can do proper bookkeeping. When you construct a BMidiLocalProducer or
|
||||
BMidiLocalConsumer endpoint, it starts with a reference count of 1. In
|
||||
addition, BMidiRoster increments the reference count of any object it hands to
|
||||
you as a result of BMidiRoster::NextEndpoint() or
|
||||
BMidiRoster::FindEndpoint(). Once the count hits
|
||||
0, the endpoint will be deleted.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
This means that, to delete an endpoint, you don't call the <function>delete</function>
|
||||
operator directly; instead, you call BMidiEndpoint::Release(). To balance this call,
|
||||
there's also an BMidiEndpoint::Acquire(), in case you have two disparate parts of
|
||||
your application working with the endpoint, and you don't want to have to keep
|
||||
track of who needs to Release() the endpoint.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
When you're done with any endpoint object, you must Release() it. This is true
|
||||
for both local and remote objects. Repeat after me: Release() when you're done.
|
||||
</para>
|
||||
</sect2>
|
||||
|
||||
<sect2 id="midi2events">
|
||||
<title>MIDI Events</title>
|
||||
|
||||
<para>
|
||||
To make some actual music, you need to BMidiProducer::Connect()
|
||||
your consumers to your producers. Then you tell the producer to
|
||||
"spray" MIDI events to all the connected consumers. The consumers are notified
|
||||
of these incoming events through a set of hook functions.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The Midi Kit already provides a set of commonly used spray functions, such as
|
||||
BMidiLocalProducer::SprayNoteOn(), BMidiLocalProducer::SprayControlChange(), and so
|
||||
on. These correspond one-to-one with the message types from the MIDI spec. You
|
||||
don't need to be a MIDI expert to use the kit, but of course some knowledge of
|
||||
the protocol helps. If you are really hardcore, you can also use the
|
||||
BMidiLocalProducer::SprayData() to send raw MIDI events to
|
||||
the consumers.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
At the consumer side, a dedicated thread invokes a hook function for every
|
||||
incoming MIDI event. For every spray function, there is a corresponding hook
|
||||
function, e.g. BMidiLocalConsumer::NoteOn() and
|
||||
BMidiLocalConsumer::ControlChange(). The hardcore MIDI
|
||||
fanatics among you will be pleased to know that you can also tap into the
|
||||
BMidiLocalConsumer::Data() hook and get your hands dirty with
|
||||
the raw MIDI data.
|
||||
</para>
|
||||
</sect2>
|
||||
|
||||
<sect2 id="midi2time">
|
||||
<title>Time</title>
|
||||
<para>
|
||||
The spray and hook functions accept a bigtime_t parameter named "time". This
|
||||
indicates when the MIDI event should be performed. The time is given in
|
||||
microseconds since the computer booted. To get the current tick measurement,
|
||||
you call the system_time() function from the Kernel Kit.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
If you override a hook function in one of your consumer objects, it should look
|
||||
at the time argument, wait until the designated time, and then perform its
|
||||
action. The preferred method is to use the Kernel Kit's
|
||||
<function>snooze_until()</function> function, which sends the consumer thread to sleep
|
||||
until the requested time has come. (Or, if the time has already passed, returns
|
||||
immediately.)
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Like this:
|
||||
<programlisting>
|
||||
void MyConsumer::NoteOn(
|
||||
uchar channel, uchar note, uchar velocity, bigtime_t time)
|
||||
{
|
||||
snooze_until(time, B_SYSTEM_TIMEBASE);
|
||||
...do your thing...
|
||||
}
|
||||
</programlisting>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
If you want your producers to run in real time, i.e. they produce MIDI data
|
||||
that needs to be performed immediately, you should pass time 0 to the spray
|
||||
functions (which also happens to be the default value). Since time 0 has
|
||||
already passed, <function>snooze_until()</function> returns immediately, and the
|
||||
consumer will process the events as soon as they are received.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
To schedule MIDI events for a performance time that lies somewhere in the
|
||||
future, the producer must take into account the consumer's latency. Producers
|
||||
should attempt to get notes to the consumer by or before
|
||||
<emphasis>(scheduled_performance_time - latency)</emphasis>. The time argument is still the
|
||||
scheduled performance time, so if your consumer has latency, it should snooze
|
||||
like this before it starts to perform the events:
|
||||
<programlisting>
|
||||
snooze_until(time - Latency(), B_SYSTEM_TIMEBASE);
|
||||
</programlisting>
|
||||
</para>
|
||||
|
||||
<note><para>
|
||||
Note that a typical producer sends out its events as soon as it can; unlike a
|
||||
consumer, it does not have to snooze.
|
||||
</para></note>
|
||||
</sect2>
|
||||
|
||||
<sect2 id="midi2ports">
|
||||
<title>Other Timing Issues</title>
|
||||
|
||||
<para>
|
||||
Each consumer object uses a Kernel Kit port to receive MIDI events from
|
||||
connected producers. The queue for this port is only 1 message deep. This means
|
||||
that if the consumer thread is asleep in a <function>snooze_until()</function>, it will
|
||||
not read its port. Consequently, any producer that tries to write a new event
|
||||
to this port will block until the consumer thread is ready to receive a new
|
||||
message. This is intentional, because it prevents producers from generating and
|
||||
queueing up thousands of events.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
This mechanism, while simple, puts on the producer the responsibility for
|
||||
sorting the events in time. Suppose your producer sends three Note On events,
|
||||
the first on t + 0, the second on t + 4, and the third on t + 2. This last
|
||||
event won't be received until after t + 4, so it will be two ticks too late. If
|
||||
this sort of thing can happen with your producer, you should somehow sort the
|
||||
events before you spray them. Of course, if you have two or more producers
|
||||
connected to the same consumer, it is nearly impossible to sort this all out
|
||||
(pardon the pun). So it is not wise to send the same kinds of events from more
|
||||
than one producer to one consumer at the same time.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The article Introduction to MIDI, Part 2 in <ulink
|
||||
url="http://haiku-os.org/learn.php?mode=nsl_view&id=36">Haiku
|
||||
Newsletter 36</ulink> describes this problem in more detail, and provides a
|
||||
solution. Go read it now!
|
||||
</para>
|
||||
</sect2>
|
||||
|
||||
<sect2 id="midi2filters">
|
||||
<title>Writing a Filter</title>
|
||||
|
||||
<para>
|
||||
A typical filter contains a consumer and a producer endpoint. It receives
|
||||
events from the consumer, processes them, and sends them out again using the
|
||||
producer. The consumer endpoint is a subclass of BMidiLocalConsumer, whereas
|
||||
the producer is simply a BMidiLocalProducer, not a subclass. This is a common
|
||||
configuration, because consumers work by overriding the event hooks to do work
|
||||
when MIDI data arrives. Producers work by sending an event when you call their
|
||||
member functions. You should hardly ever need to derive from BMidiLocalProducer
|
||||
(unless you need to know when the producer gets connected or disconnected,
|
||||
perhaps), but you'll always have to override one or more of
|
||||
BMidiLocalConsumer's member functions to do something useful with incoming
|
||||
data.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Filters should ignore the time argument from the spray and hook functions, and
|
||||
simply pass it on unchanged. Objects that only filter data should process the
|
||||
event as quickly as possible and be done with it. Do not
|
||||
<function>snooze_until()</function> in the consumer endpoint of a filter!
|
||||
</para>
|
||||
</sect2>
|
||||
|
||||
<sect2 id="midi2apidiffs">
|
||||
<title>API Differences</title>
|
||||
|
||||
<para>
|
||||
As far as the end user is concerned, the OpenBeOS Midi Kit is mostly the same
|
||||
as the BeOS R5 kits, although there are a few small differences in the API
|
||||
(mostly bug fixes):
|
||||
<itemizedlist>
|
||||
<listitem><para>BMidiEndpoint::IsPersistent() always returns false.</para></listitem>
|
||||
<listitem><para>The B_MIDI_CHANGE_LATENCY notification is now properly sent. The Be kit
|
||||
incorrectly set be:op to B_MIDI_CHANGED_NAME, even though the rest of the
|
||||
message was properly structured.</para></listitem>
|
||||
<listitem><para>If creating a local endpoint fails, you can still Release() the object
|
||||
without crashing into the debugger.</para></listitem>
|
||||
</itemizedlist>
|
||||
</para>
|
||||
</sect2>
|
||||
|
||||
<sect2 id="midi2seealso">
|
||||
<title>See Also</title>
|
||||
|
||||
<para>
|
||||
More about the Midi Kit:
|
||||
<itemizedlist>
|
||||
<listitem><para>Be Newsletter Volume 3, Issue 47 - Motor Mix sample code</para></listitem>
|
||||
<listitem><para>Be Newsletter Volume 4, Issue 3 - Overview of the new kit</para></listitem>
|
||||
<listitem><para><ulink url="http://haiku-os.org/learn.php?mode=nsl_view&id=33">Haiku
|
||||
Newsletter 33</ulink>, Introduction to MIDI, Part 1</para></listitem>
|
||||
<listitem><para><ulink url="http://haiku-os.org/learn.php?mode=nsl_view&id=36">Haiku
|
||||
Newsletter 36</ulink>, Introduction to MIDI, Part 2</para></listitem>
|
||||
<listitem><para>Sample code and other goodies at the
|
||||
<ulink url="http://haiku-os.org/contribute.php?mode=team_view&id=midi">OpenBeOS Midi Kit team page</ulink></para></listitem>
|
||||
</itemizedlist>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Information about MIDI in general:
|
||||
<itemizedlist>
|
||||
<listitem><para><ulink url="http://www.midi.org">MIDI Manufacturers Association</ulink></para></listitem>
|
||||
<listitem><para><ulink url="http://www.borg.com/~jglatt/tutr/miditutr.htm">MIDI Tutorials</ulink></para></listitem>
|
||||
<listitem><para><ulink url="http://www.borg.com/~jglatt/tech/midispec.htm">MIDI Specification</ulink></para></listitem>
|
||||
<listitem><para><ulink url="http://www.borg.com/~jglatt/tech/midifile.htm">Standard MIDI File Format</ulink></para></listitem>
|
||||
<listitem><para><ulink url="http://www.io.com/~jimm/midi_ref.html">Jim Menard's MIDI Reference</ulink></para></listitem>
|
||||
</itemizedlist>
|
||||
</para>
|
||||
</sect2>
|
||||
</sect1>
|
||||
|
||||
|
||||
@@ -1,63 +0,0 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
||||
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
|
||||
|
||||
<!ENTITY midi2defs SYSTEM "midi2defs.xml">
|
||||
<!ENTITY midi2consumer SYSTEM "midi2consumer.xml">
|
||||
<!ENTITY midi2endpoint SYSTEM "midi2endpoint.xml">
|
||||
<!ENTITY midi2localconsumer SYSTEM "midi2localconsumer.xml">
|
||||
<!ENTITY midi2localproducer SYSTEM "midi2localproducer.xml">
|
||||
<!ENTITY midi2producer SYSTEM "midi2producer.xml">
|
||||
<!ENTITY midi2roster SYSTEM "midi2roster.xml">
|
||||
|
||||
<!ENTITY BMidiRoster "<link linkend='bmidiroster'><classname>BMidiRoster</classname></link>">
|
||||
<!ENTITY BMidiRoster_FindEndpoint "<link linkend='bmidiroster_findendpoint'><function>FindEndpoint()</function></link>">
|
||||
<!ENTITY BMidiRoster_NextEndpoint "<link linkend='bmidiroster_nextendpoint'><function>NextEndpoint()</function></link>">
|
||||
<!ENTITY BMidiRoster_Register "<link linkend='bmidiroster_register'><function>Register()</function></link>">
|
||||
<!ENTITY BMidiRoster_Unregister "<link linkend='bmidiroster_unregister'><function>Unregister()</function></link>">
|
||||
<!ENTITY BMidiRoster_StartWatching "<link linkend='bmidiroster_startwatching'><function>StartWatching()</function></link>">
|
||||
|
||||
<!ENTITY BMidiEndpoint "<link linkend='bmidiendpoint'><classname>BMidiEndpoint</classname></link>">
|
||||
<!ENTITY BMidiEndpoint_Name "<link linkend='bmidiendpoint_name'><function>Name()</function></link>">
|
||||
<!ENTITY BMidiEndpoint_SetName "<link linkend='bmidiendpoint_setname'><function>SetName()</function></link>">
|
||||
<!ENTITY BMidiEndpoint_ID "<link linkend='bmidiendpoint_id'><function>ID()</function></link>">
|
||||
<!ENTITY BMidiEndpoint_Register "<link linkend='bmidiendpoint_register'><function>Register()</function></link>">
|
||||
<!ENTITY BMidiEndpoint_Unregister "<link linkend='bmidiendpoint_unregister'><function>Unregister()</function></link>">
|
||||
<!ENTITY BMidiEndpoint_IsProducer "<link linkend='bmidiendpoint_isproducer'><function>IsProducer()</function></link>">
|
||||
<!ENTITY BMidiEndpoint_IsConsumer "<link linkend='bmidiendpoint_isconsumer'><function>IsConsumer()</function></link>">
|
||||
<!ENTITY BMidiEndpoint_IsRemote "<link linkend='bmidiendpoint_isremote'><function>IsRemote()</function></link>">
|
||||
<!ENTITY BMidiEndpoint_IsLocal "<link linkend='bmidiendpoint_islocal'><function>IsLocal()</function></link>">
|
||||
<!ENTITY BMidiEndpoint_IsPersistent "<link linkend='bmidiendpoint_ispersistent'><function>IsPersistent()</function></link>">
|
||||
<!ENTITY BMidiEndpoint_IsValid "<link linkend='bmidiendpoint_isvalid'><function>IsValid()</function></link>">
|
||||
<!ENTITY BMidiEndpoint_Acquire "<link linkend='bmidiendpoint_acquire'><function>Acquire()</function></link>">
|
||||
<!ENTITY BMidiEndpoint_Release "<link linkend='bmidiendpoint_release'><function>Release()</function></link>">
|
||||
<!ENTITY BMidiEndpoint_SetProperties "<link linkend='bmidiendpoint_setproperties'><function>SetProperties()</function></link>">
|
||||
<!ENTITY BMidiEndpoint_GetProperties "<link linkend='bmidiendpoint_getproperties'><function>GetProperties()</function></link>">
|
||||
|
||||
<!ENTITY BMidiLocalConsumer "<link linkend='midi2localconsumer'><classname>BMidiLocalConsumer</classname></link>">
|
||||
<!ENTITY BMidiLocalConsumer_ChannelPressure "<link linkend='bmidilocalconsumer_channelpressure'><function>BMidiLocalConsumer</function></link>">
|
||||
<!ENTITY BMidiLocalConsumer_Timeout "<link linkend='bmidilocalconsumer_timeout'><function>Timeout</function></link>">
|
||||
|
||||
<!ENTITY BMidiLocalProducer "<link linkend='bmidilocalproducer'><classname>BMidiLocalProducer</classname></link>">
|
||||
|
||||
<!ENTITY BMidiProducer "<link linkend='bmidiproducer'><classname>BMidiProducer</classname></link>">
|
||||
<!ENTITY BMidiProducer_Connect "<link linkend='bmidiproducer_connect'><function>Connect()</function></link>">
|
||||
<!ENTITY BMidiProducer_Disconnect "<link linkend='bmidiproducer_disconnect'><function>Disconnect()</function></link>">
|
||||
|
||||
<!ENTITY BMidiConsumer "<link linkend='bmidiconsumer'><classname>BMidiConsumer</classname></link>">
|
||||
<!ENTITY BMidiConsumer_Latency "<link linkend='bmidiconsumer_latency'><function>Latency()</function></link>">
|
||||
|
||||
]>
|
||||
|
||||
<sect1 id="midi2api">
|
||||
<title>Midi 2 Kit API</title>
|
||||
|
||||
&midi2defs;
|
||||
&midi2roster;
|
||||
&midi2endpoint;
|
||||
&midi2consumer;
|
||||
&midi2producer;
|
||||
&midi2localconsumer;
|
||||
&midi2localproducer;
|
||||
</sect1>
|
||||
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 28 KiB |
@@ -1,72 +0,0 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
|
||||
<sect2 id="bmidiconsumer">
|
||||
<title>BMidiConsumer</title>
|
||||
|
||||
<para>
|
||||
A consumer is an object that knows how to deal with incoming MIDI events. A
|
||||
consumer can be connected to multiple producers at the same time. There is no
|
||||
way to find out which producers are connected to this consumer just by looking
|
||||
at the &BMidiConsumer; object; you will have to consult &BMidiRoster; for that.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
A &BMidiConsumer; either represents a local consumer, i.e. a class extending from
|
||||
&BMidiLocalConsumer;, or is a proxy for a remote object published by another app.
|
||||
</para>
|
||||
|
||||
<sect3 id="BMidiConsumer_Latency">
|
||||
<title>Latency()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>bigtime_t</type>
|
||||
<methodname>Latency</methodname><void/>
|
||||
<modifier>const</modifier>
|
||||
</methodsynopsis>
|
||||
|
||||
<para>
|
||||
The latency is measured in microseconds. Producers should attempt to get MIDI
|
||||
events to this consumer by <emphasis>(when - latency)</emphasis>. You do this by subtracting
|
||||
the latency from the performance time when you spray the events (provided that
|
||||
you spray these events ahead of time, of course).
|
||||
</para>
|
||||
|
||||
<para>
|
||||
You cannot <emphasis>set</emphasis> the latency on a &BMidiConsumer;, only on a
|
||||
&BMidiLocalConsumer;.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The latency issue gets slightly more complicated when multiple endpoints are
|
||||
chained together, as in the following picture:
|
||||
|
||||
<programlisting>
|
||||
+-------+ +-------------+ +-------+
|
||||
| | | | | |
|
||||
| prodA |---->| consB prodB |---->| consC |
|
||||
| | | | | |
|
||||
+-------+ +-------------+ +-------+
|
||||
appA appB (filter) appC
|
||||
</programlisting>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Suppose consC has 200ms latency, and consB has 100ms latency. If consB simply
|
||||
reports 100ms, then prodA will schedule its events for (t - 100), which is
|
||||
really 200ms too late. (Of course, producers send out their events as soon as
|
||||
possible, so depending on the load of the system, everything may work out just
|
||||
fine.)
|
||||
</para>
|
||||
|
||||
<para>
|
||||
ConsB should report the latency of the consumer that is hooked up to its
|
||||
output, consC, in addition to its own latency. In other words, the full
|
||||
downstream latency. So, the reported latency in this case would be 300ms. This
|
||||
also means that appB should change the latency of consB when prodB makes or
|
||||
breaks a connection, and when consC reports a latency change. (If multiple
|
||||
consumers are connected to prodB, you should take the slowest one.)
|
||||
Unfortunately, the Midi Kit provides no easy mechanism for doing any of this,
|
||||
so you are on your own here.
|
||||
</para>
|
||||
</sect3>
|
||||
</sect2>
|
||||
@@ -1,285 +0,0 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
|
||||
<sect2 id="midi2defs">
|
||||
<title>Midi Defs</title>
|
||||
|
||||
<para>
|
||||
The <filename>Midi2Defs.h</filename> defines a series of constants that are used throughout
|
||||
the Kit.
|
||||
</para>
|
||||
|
||||
<table id="midichannelmask">
|
||||
<title>Channel message masks</title>
|
||||
<tgroup cols='2' align='left' colsep='1' rowsep='1'>
|
||||
<colspec colname='constant'/>
|
||||
<colspec colname='value'/>
|
||||
<tbody>
|
||||
<row>
|
||||
<entry><constant>B_NOTE_OFF</constant></entry>
|
||||
<entry>0x80</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><constant>B_NOTE_ON</constant></entry>
|
||||
<entry>0x90</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><constant>B_KEY_PRESSURE</constant></entry>
|
||||
<entry>0xa0</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><constant>B_CONTROL_CHANGE</constant></entry>
|
||||
<entry>0xb0</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><constant>B_PROGRAM_CHANGE</constant></entry>
|
||||
<entry>0xc0</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><constant>B_CHANNEL_PRESSURE</constant></entry>
|
||||
<entry>0xd0</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><constant>B_PITCH_BEND</constant></entry>
|
||||
<entry>0xe0</entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</table>
|
||||
|
||||
<table id="midisystemmessages">
|
||||
<title>System Messages</title>
|
||||
<tgroup cols='2' align='left' colsep='1' rowsep='1'>
|
||||
<colspec colname='constant'/>
|
||||
<colspec colname='value'/>
|
||||
<tbody>
|
||||
<row>
|
||||
<entry><constant>B_SYS_EX_START</constant></entry>
|
||||
<entry>0xf0</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><constant>B_MIDI_TIME_CODE</constant></entry>
|
||||
<entry>0xf1</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><constant>B_SONG_POSITION</constant></entry>
|
||||
<entry>0xf2</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><constant>B_SONG_SELECT</constant></entry>
|
||||
<entry>0xf3</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><constant>B_CABLE_MESSAGE</constant></entry>
|
||||
<entry>0xf5</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><constant>B_TUNE_REQUEST</constant></entry>
|
||||
<entry>0xf6</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><constant>B_SYS_EX_END</constant></entry>
|
||||
<entry>0xf7</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><constant>B_TIMING_CLOCK</constant></entry>
|
||||
<entry>0xf8</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><constant>B_START</constant></entry>
|
||||
<entry>0xfa</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><constant>B_CONTINUE</constant></entry>
|
||||
<entry>0xfb</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><constant>B_STOP</constant></entry>
|
||||
<entry>0xfc</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><constant>B_ACTIVE_SENSING</constant></entry>
|
||||
<entry>0xfe</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><constant>B_SYSTEM_RESET</constant></entry>
|
||||
<entry>0xff</entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</table>
|
||||
|
||||
<table id="midicontrollernumbers">
|
||||
<title>Controller numbers</title>
|
||||
<tgroup cols='2' align='left' colsep='1' rowsep='1'>
|
||||
<colspec colname='constant'/>
|
||||
<colspec colname='value'/>
|
||||
<tbody>
|
||||
<row>
|
||||
<entry><constant>B_MODULATION</constant></entry>
|
||||
<entry>0x01</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><constant>B_BREATH_CONTROLLER</constant></entry>
|
||||
<entry>0x02</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><constant>B_FOOT_CONTROLLER</constant></entry>
|
||||
<entry>0x04</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><constant>B_PORTAMENTO_TIME</constant></entry>
|
||||
<entry>0x05</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><constant>B_DATA_ENTRY</constant>
|
||||
</entry><entry>0x06</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><constant>B_MAIN_VOLUME</constant></entry>
|
||||
<entry>0x07</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><constant>B_MIDI_BALANCE</constant></entry>
|
||||
<entry>0x08</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><constant>B_PAN</constant></entry>
|
||||
<entry>0x0a</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><constant>B_EXPRESSION_CTRL</constant></entry>
|
||||
<entry>0x0b</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><constant>B_GENERAL_CTRL_1</constant></entry>
|
||||
<entry>0x10</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><constant>B_GENERAL_CTRL_2</constant></entry>
|
||||
<entry>0x11</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><constant>B_GENERAL_CTRL_3</constant></entry>
|
||||
<entry>0x12</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><constant>B_GENERAL_CTRL_4</constant></entry>
|
||||
<entry>0x13</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><constant>B_SUSTAIN_PEDAL</constant></entry>
|
||||
<entry>0x40</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><constant>B_PORTAMENTO</constant></entry>
|
||||
<entry>0x41</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><constant>B_SOSTENUTO</constant></entry>
|
||||
<entry>0x42</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><constant>B_SOFT_PEDAL</constant></entry>
|
||||
<entry>0x43</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><constant>B_HOLD_2</constant></entry>
|
||||
<entry>0x45</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><constant>B_GENERAL_CTRL_5</constant></entry>
|
||||
<entry>0x50</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><constant>B_GENERAL_CTRL_6</constant></entry>
|
||||
<entry>0x51</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><constant>B_TEMPO_CHANGE</constant></entry>
|
||||
<entry>0x51</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><constant>B_GENERAL_CTRL_7</constant></entry>
|
||||
<entry>0x52</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><constant>B_GENERAL_CTRL_8</constant></entry>
|
||||
<entry>0x53</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><constant>B_EFFECTS_DEPTH</constant></entry>
|
||||
<entry>0x5b</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><constant>B_TREMOLO_DEPTH</constant></entry>
|
||||
<entry>0x5c</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><constant>B_CHORUS_DEPTH</constant></entry>
|
||||
<entry>0x5d</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><constant>B_CELESTE_DEPTH</constant></entry>
|
||||
<entry>0x5e</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><constant>B_PHASER_DEPTH</constant></entry>
|
||||
<entry>0x5f</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><constant>B_DATA_INCREMENT</constant></entry>
|
||||
<entry>0x60</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><constant>B_DATA_DECREMENT</constant></entry>
|
||||
<entry>0x61</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><constant>B_RESET_ALL_CONTROLLERS</constant></entry>
|
||||
<entry>0x79</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><constant>B_LOCAL_CONTROL</constant></entry>
|
||||
<entry>0x7a</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><constant>B_ALL_NOTES_OFF</constant></entry>
|
||||
<entry>0x7b</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><constant>B_OMNI_MODE_OFF</constant></entry>
|
||||
<entry>0x7c</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><constant>B_OMNI_MODE_ON</constant></entry>
|
||||
<entry>0x7d</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><constant>B_MONO_MODE_ON</constant></entry>
|
||||
<entry>0x7e</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><constant>B_POLY_MODE_ON</constant></entry>
|
||||
<entry>0x7f</entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</table>
|
||||
|
||||
<table id="bmidiop">
|
||||
<title>BMidiOp</title>
|
||||
<tgroup cols='1' align='left' colsep='1' rowsep='1'>
|
||||
<colspec colname='constant'/>
|
||||
<tbody>
|
||||
<row><entry>B_MIDI_NO_OP</entry></row>
|
||||
<row><entry>B_MIDI_REGISTERED</entry></row>
|
||||
<row><entry>B_MIDI_UNREGISTERED</entry></row>
|
||||
<row><entry>B_MIDI_CONNECTED</entry></row>
|
||||
<row><entry>B_MIDI_DISCONNECTED</entry></row>
|
||||
<row><entry>B_MIDI_CHANGED_NAME</entry></row>
|
||||
<row><entry>B_MIDI_CHANGED_LATENCY</entry></row>
|
||||
<row><entry>B_MIDI_CHANGED_PROPERTIES</entry></row>
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</table>
|
||||
</sect2>
|
||||
@@ -1,520 +0,0 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
|
||||
<sect2 id="bmidiendpoint">
|
||||
<title>BMidiEndpoint</title>
|
||||
|
||||
<para>
|
||||
The <filename>MidiEndpoint.h</filename> file defines the &BMidiEndpoint;,
|
||||
which is the baseclass for all MIDI endpoints.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
&BMidiEndpoint; is the abstract base class that represents either a producer or
|
||||
consumer endpoint. It may be used to obtain the state, name, properties, or
|
||||
system-wide ID of the object. &BMidiEndpoint; also provides the ability to change
|
||||
the name and properties of endpoints that were created locally.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Remember, you cannot call the destructor of &BMidiEndpoint; and its subclasses
|
||||
directly. Endpoint objects are destructed automatically when their reference
|
||||
count drops to zero. If necessary, the destructor of a local endpoint first
|
||||
breaks off any connections and &BMidiEndpoint_Unregister;'s the endpoint before it is
|
||||
deleted. However, for good style and bonus points you should really
|
||||
&BMidiProducer_Disconnect; and &BMidiEndpoint_Unregister; the object
|
||||
yourself and not rely on the destructor to do this.
|
||||
</para>
|
||||
|
||||
<bridgehead renderas="sect2">Member Functions</bridgehead>
|
||||
|
||||
<sect3 id="bmidiendpoint_name">
|
||||
<title>Name()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<modifier>const</modifier><type>char *</type>
|
||||
<methodname>Name</methodname><void/>
|
||||
<modifier>const</modifier>
|
||||
</methodsynopsis>
|
||||
|
||||
<para>
|
||||
Returns the name of the endpoint.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The function never returns NULL. If you created a local endpoint by passing a
|
||||
NULL name into its constructor (or passing no name, which is the same thing),
|
||||
then &BMidiEndpoint_Name; will return an empty string, not NULL.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
See also &BMidiEndpoint_SetName;.
|
||||
</para>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bmidiendpoint_setname">
|
||||
<title>SetName()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<void/> <methodname>SetName</methodname>
|
||||
<methodparam><modifier>const</modifier><type>char *</type><parameter>name</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
|
||||
<para>
|
||||
Changes the name of the endpoint.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Names don't have to be unique, but it is recommended that you give any
|
||||
endpoints you publish meaningful and unique names, so users can easily
|
||||
recognize what each endpoint does. There is no limit to the size of endpoint
|
||||
names.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Even though you can call this function on both remote and local objects, you
|
||||
are only allowed to change the names of local endpoints; &BMidiEndpoint_SetName;
|
||||
calls on remote endpoints are ignored.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<parameter>name</parameter> The new name. If you pass NULL, the name simply won't be changed.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
See also &BMidiEndpoint_Name;.
|
||||
</para>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bmidiendpoint_id">
|
||||
<title>ID()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>int32</type> <methodname>ID</methodname> <void/> <modifier>const</modifier>
|
||||
</methodsynopsis>
|
||||
|
||||
<para>
|
||||
Returns the ID of the endpoint.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
An ID uniquely identifies an endpoint in the system. The ID is a signed 32-bit
|
||||
number that is assigned by the Midi Server when the endpoint is created. (So
|
||||
even if a local endpoint is not published, it still has a unique ID.) Valid IDs
|
||||
range from 1 to 0x7FFFFFFF, the largest value an int32 can have. 0 and negative
|
||||
values are <emphasis>not</emphasis> valid IDs.
|
||||
</para>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bmidiendpoint_isproducer">
|
||||
<title>IsProducer()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>bool</type> <methodname>IsProducer</methodname> <void/> <modifier>const</modifier>
|
||||
</methodsynopsis>
|
||||
|
||||
<para>
|
||||
Determines whether this endpoint is a &BMidiProducer;.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
If it is, you can use a dynamic_cast to convert this object into a producer:
|
||||
|
||||
<programlisting>
|
||||
if (endp->IsProducer())
|
||||
{
|
||||
BMidiProducer* prod = dynamic_cast <BMidiProducer*>(endp);
|
||||
....
|
||||
}
|
||||
</programlisting>
|
||||
</para>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bmidiendpoint_isconsumer">
|
||||
<title>IsConsumer()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>bool</type> <methodname>IsConsumer</methodname> <void/> <modifier>const</modifier>
|
||||
</methodsynopsis>
|
||||
|
||||
<para>
|
||||
Determines whether this endpoint is a &BMidiConsumer;.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
If it is, you can use a dynamic_cast to convert this object into a consumer:
|
||||
<programlisting>
|
||||
if (endp->IsConsumer())
|
||||
{
|
||||
BMidiConsumer* cons = dynamic_cast<BMidiConsumer*>(endp);
|
||||
....
|
||||
}
|
||||
</programlisting>
|
||||
</para>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bmidiendpoint_isremote">
|
||||
<title>IsRemote()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>bool</type> <methodname>IsRemote</methodname> <void/> <modifier>const</modifier>
|
||||
</methodsynopsis>
|
||||
|
||||
<para>
|
||||
Determines whether this endpoint is a proxy for a remote object.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
An endpoint is "remote" when it is created by another application. Obviously,
|
||||
the remote object is &BMidiEndpoint_Register;'ed as well, otherwise you would not be able to
|
||||
see it.
|
||||
</para>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bmidiendpoint_islocal">
|
||||
<title>IsLocal()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>bool</type> <methodname>IsLocal</methodname> <void/> <modifier>const</modifier>
|
||||
</methodsynopsis>
|
||||
|
||||
<para>
|
||||
Determines whether this endpoint represents a local object.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
An endpoint is "local" when it is created by this application; in other words,
|
||||
a &BMidiLocalConsumer; or &BMidiLocalProducer;.
|
||||
</para>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bmidiendpoint_ispersistent">
|
||||
<title>IsPersistent()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>bool</type> <methodname>IsPersistent</methodname> <void/> <modifier>const</modifier>
|
||||
</methodsynopsis>
|
||||
|
||||
<para>
|
||||
Not used.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The purpose of this function is unclear, and as a result it doesn't do anything
|
||||
in the Haiku implementation of the Midi Kit.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Always returns false.
|
||||
</para>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bmidiendpoint_isvalid">
|
||||
<title>IsValid()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>bool</type> <methodname>IsValid</methodname> <void/> <modifier>const</modifier>
|
||||
</methodsynopsis>
|
||||
|
||||
<para>
|
||||
Determines whether the endpoint still exists
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Suppose you obtained a proxy object for a remote endpoint by querying the
|
||||
&BMidiRoster;. What if the application that published this endpoint quits, or
|
||||
less drastically, &BMidiEndpoint_Unregister;'s that endpoint? Even though you still have a
|
||||
&BMidiEndpoint; proxy object, the real endpoint no longer exists. You can use
|
||||
&BMidiEndpoint_IsValid; to check for this.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Don't worry, operations on invalid objects, such as &BMidiEndpoint_GetProperties;, will
|
||||
return an error code (typically B_ERROR), but not cause a crash. Local objects
|
||||
are always are considered to be valid, even if you did not &BMidiEndpoint_Register; them.
|
||||
(The only time a local endpoint is not valid is when there was a problem
|
||||
constructing it.)
|
||||
</para>
|
||||
|
||||
<para>
|
||||
If the application that created the remote endpoint crashes, then there is no
|
||||
guarantee that the Midi Server immediately recognizes this. In that case,
|
||||
&BMidiEndpoint_IsValid; may still return true. Eventually, the stale endpoint will be removed
|
||||
from the roster, though. From then on, &BMidiEndpoint_IsValid; correctly returns false.
|
||||
</para>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bmidiendpoint_acquire">
|
||||
<title>Acquire()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>status_t</type> <methodname>Acquire</methodname> <void/>
|
||||
</methodsynopsis>
|
||||
|
||||
<para>
|
||||
Increments the endpoint's reference count
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Each &BMidiEndpoint; has a reference count associated with it, so that
|
||||
&BMidiRoster; can do proper bookkeeping. &BMidiEndpoint_Acquire; increments this reference
|
||||
count, and &BMidiEndpoint_Release; decrements it. Once the count reaches zero, the endpoint
|
||||
is deleted.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
When you are done with the endpoint, whether local or remote, you should
|
||||
<emphasis>always</emphasis> &BMidiEndpoint_Release; it!
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Upon construction, local endpoints start with a reference count of 1. Any
|
||||
objects you obtain from &BMidiRoster; using the NextXXX() or FindXXX() functions
|
||||
have their reference counts incremented in the process. If you forget to call
|
||||
&BMidiEndpoint_Release;, the objects won't be properly cleaned up and you'll make a fool out
|
||||
of yourself.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
After you &BMidiEndpoint_Release; an object, you are advised not to use it any further. If
|
||||
you do, your app will probably crash. That also happens if you &BMidiEndpoint_Release; an
|
||||
object too many times.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Typically, you don't need to call &BMidiEndpoint_Acquire;, unless you have two disparate
|
||||
parts of your application working with the same endpoint, and you don't want to
|
||||
have to keep track of who needs to &BMidiEndpoint_Release; the endpoint. Now you simply have
|
||||
both of them release it.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Always returns B_OK.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
See also &BMidiEndpoint_Release;.
|
||||
</para>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bmidiendpoint_release">
|
||||
<title>Release()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>status_t</type> <methodname>Release</methodname> <void/>
|
||||
</methodsynopsis>
|
||||
|
||||
<para>
|
||||
Decrements the endpoint's reference count.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Always returns B_OK.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
See also &BMidiEndpoint_Acquire;
|
||||
</para>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bmidiendpoint_register">
|
||||
<title>Register()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>status_t</type> <methodname>Register</methodname> <void/>
|
||||
</methodsynopsis>
|
||||
|
||||
<para>
|
||||
Publishes the endpoint on the roster.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
MIDI objects created by an application are invisible to other applications
|
||||
until they are published. To publish an object use the &BMidiEndpoint_Register;
|
||||
method. The corresponding &BMidiEndpoint_Unregister; method will cause an object to
|
||||
once again become invisible to remote applications.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
&BMidiRoster; also has &BMidiRoster_Register; and &BMidiRoster_Unregister; methods. You may also use
|
||||
those methods to publish or hide your endpoints; both do the same thing.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Although it is considered bad style, calling &BMidiEndpoint_Register; on local endpoints that
|
||||
are already registered won't mess things up. The Midi Server will simply ignore
|
||||
your request. Likewise for &BMidiEndpoint_Unregister;'ing more than once. Attempts to
|
||||
&BMidiEndpoint_Register; or &BMidiEndpoint_Unregister; remote endpoints will fail, of course.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
If you are &BMidiRoster_StartWatching; watching, you will
|
||||
<emphasis>not</emphasis> receive notifications for any local endpoints you register or
|
||||
unregister. Of course, other applications <emphasis>will</emphasis> be notified about your
|
||||
endpoints.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Existing connections will not be broken when an object is unregistered, but
|
||||
future remote connections will be denied. When objects are destroyed, they
|
||||
automatically become unregistered.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Returns B_OK on success, or a negative error code (typically B_ERROR) if
|
||||
something went wrong.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
See also &BMidiEndpoint_Unregister;.
|
||||
</para>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bmidiendpoint_unregister">
|
||||
<title>Unregister()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>status_t</type> <methodname>Unregister</methodname> <void/>
|
||||
</methodsynopsis>
|
||||
|
||||
<para>
|
||||
Hides the endpoint from the roster.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
See also &BMidiEndpoint_Register;.
|
||||
</para>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bmidiendpoint_setproperties">
|
||||
<title>SetProperties()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>status_t</type> <methodname>SetProperties</methodname>
|
||||
<methodparam><modifier>const</modifier><type>BMessage *</type><parameter>properties</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
|
||||
<para>
|
||||
Changes the properties of the endpoint.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Endpoints can have properties, which is any kind of information that might be
|
||||
useful to associate with a MIDI object. The properties are stored in a
|
||||
BMessage.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Usage example:
|
||||
|
||||
<programlisting>
|
||||
BMessage props;
|
||||
if (endpoint->GetProperties(&props) == B_OK)
|
||||
{
|
||||
...add data to the message...
|
||||
endpoint->SetProperties(&props);
|
||||
}
|
||||
</programlisting>
|
||||
</para>
|
||||
|
||||
|
||||
<para>
|
||||
You are only allowed to call &BMidiEndpoint_SetProperties; on a local object.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Properties should follow a protocol, so different applications will know how to
|
||||
read each other's properties. The current protocol is very limited -- it only
|
||||
allows you to associate icons with your endpoints. Be planned to publish a more
|
||||
complete protocol that included additional information, such as vendor/model
|
||||
names, copyright/version info, category, etc., but they never got around to it.
|
||||
</para>
|
||||
|
||||
<table id="bmidiendpoint_property1">
|
||||
<title>Large Icon Property</title>
|
||||
<tgroup cols='2' align='left' colsep='1' rowsep='1'>
|
||||
<colspec colname='constant'/>
|
||||
<colspec colname='value'/>
|
||||
<tbody>
|
||||
<row>
|
||||
<entry>property</entry>
|
||||
<entry>Large (32x32) icon</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>field name</entry>
|
||||
<entry>"be:large_icon"</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>field type</entry>
|
||||
<entry>'ICON'</entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</table>
|
||||
|
||||
<table id="bmidiendpoint_property2">
|
||||
<title>Small Icon Property</title>
|
||||
<tgroup cols='2' align='left' colsep='1' rowsep='1'>
|
||||
<colspec colname='constant'/>
|
||||
<colspec colname='value'/>
|
||||
<tbody>
|
||||
<row>
|
||||
<entry>property</entry>
|
||||
<entry>Small (16x16) ico</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>field name</entry>
|
||||
<entry>"be:mini_icon"</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>field type</entry>
|
||||
<entry>'MICN'</entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</table>
|
||||
|
||||
<para>
|
||||
The MidiUtil package (downloadable from the Haiku website) contains a number
|
||||
of convenient functions to associate icons with endpoints, so you don't have to
|
||||
write that code all over again.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
See also &BMidiEndpoint_GetProperties;.
|
||||
</para>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bmidiendpoint_getproperties">
|
||||
<title>GetProperties()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>status_t</type> <methodname>GetProperties</methodname>
|
||||
<methodparam><type>BMessage *</type><parameter>properties</parameter></methodparam>
|
||||
<modifier>const</modifier>
|
||||
</methodsynopsis>
|
||||
|
||||
<para>
|
||||
Reads the properties of the endpoint
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Usage example:
|
||||
|
||||
<programlisting>
|
||||
BMessage props;
|
||||
if (endpoint->GetProperties(&props) == B_OK)
|
||||
{
|
||||
...examine the contents of the message...
|
||||
}
|
||||
</programlisting>
|
||||
</para>
|
||||
|
||||
<note><para>
|
||||
Note that &BMidiEndpoint_GetProperties; overwrites the contents of your BMessage.
|
||||
</para></note>
|
||||
|
||||
<para>
|
||||
See also &BMidiEndpoint_SetProperties;
|
||||
</para>
|
||||
</sect3>
|
||||
</sect2>
|
||||
@@ -1,381 +0,0 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
|
||||
<sect2 id="midi2localconsumer">
|
||||
<title>BMidiLocalConsumer</title>
|
||||
|
||||
<para>
|
||||
A consumer endpoint that is created by your own application
|
||||
</para>
|
||||
|
||||
<para>
|
||||
If you want to create a consumer that reacts to MIDI events, you should
|
||||
subclass BMidiLocalConsumer.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Each local consumer has its own thread that receives and dispatches the MIDI
|
||||
events. Whenever MIDI data arrives, the Data() hook passes the MIDI event on to
|
||||
a more specific hook function: NoteOn(), NoteOff(), SystemExclusive(), and so
|
||||
on. Calls to these hook functions are serialized -- they will never have to be
|
||||
re-entrant. They also should not be called from outside the thread that is
|
||||
invoking them.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Your subclass can override any of the MIDI event hooks. BMidiLocalConsumer
|
||||
doesn't provide default implementations for them, so you don't have to call a
|
||||
hook's default implementation if you override it. For complete control, you can
|
||||
also override Data().
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Most hook functions take a channel argument. Even though MIDI channels are
|
||||
really numbered 1 through 16, the hook functions work with channels 0 through
|
||||
15. The performance time for the event is specified in microseconds relative to
|
||||
the system time base. A performance time that is 0 (or really any time in the
|
||||
past) means "play as soon as possible". See the <xref linkend="midi2time" />
|
||||
for more information about timing and consumers.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The thread driving the consumer's events is a very high priority real time
|
||||
thread. Events should be handled as quickly as possible (not counting
|
||||
snoozing). If non-time-critical computation is needed it may be wise to queue
|
||||
events up for a lower priority thread to handle them external to the main event
|
||||
thread.
|
||||
</para>
|
||||
|
||||
<sect3 id="bmidilocalconsumer_bmidilocalconsumer">
|
||||
<title>BMidiLocalConsumer()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<methodname>BMidiLocalConsumer</methodname>
|
||||
<methodparam><modifier>const</modifier><type>char *</type><parameter>name</parameter><initializer>NULL</initializer></methodparam>
|
||||
</methodsynopsis>
|
||||
|
||||
<para>
|
||||
Creates a new local consumer endpoint.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The new endpoint is not visible to other applications until you &BMidiRoster_Register; it.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
You can tell the constructor what the name of the new consumer will be. If you
|
||||
pass NULL (or use the default argument), then the consumer's name will be an
|
||||
empty string. It won't be NULL, since endpoint names cannot be NULL.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
There is no guarantee that the endpoint will be successfully created. For
|
||||
example, the Midi Server may not be running. Therefore, you should always call
|
||||
IsValid() after creating a new endpoint to make sure that everything went okay.
|
||||
If not, &BMidiEndpoint_Release; the object to reclaim memory and abort gracefully.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<programlisting>
|
||||
MyConsumer* cons = new MyConsumer(...);
|
||||
if (!cons->IsValid())
|
||||
{
|
||||
cons->Release();
|
||||
...exit gracefully...
|
||||
}
|
||||
</programlisting>
|
||||
</para>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bmidilocalconsumer_setlatency">
|
||||
<title>SetLatency()</title>
|
||||
<methodsynopsis><void/><methodname>SetLatency</methodname><methodparam><type>bigtime_t</type><parameter>latency</parameter></methodparam></methodsynopsis>
|
||||
|
||||
<para>
|
||||
Changes the published latency of the consumer.
|
||||
</para>
|
||||
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bmidilocalconsumer_getproducerid">
|
||||
<title>GetProducerID()</title>
|
||||
<methodsynopsis><type>int32</type><methodname>GetProducerID</methodname><void/></methodsynopsis>
|
||||
|
||||
<para>
|
||||
Returns the ID of the producer that most recently sent a MIDI event to
|
||||
this consumer.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
You can call this from one of the hooks to determine which producer the event
|
||||
came from.
|
||||
</para>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bmidilocalconsumer_settimeout">
|
||||
<title>SetTimeout()</title>
|
||||
<methodsynopsis><void/><methodname>SetTimeout</methodname><methodparam><type>bigtime_t</type><parameter>when</parameter></methodparam><methodparam><type>void *</type><parameter>data</parameter></methodparam></methodsynopsis>
|
||||
|
||||
<para>
|
||||
Requests that the &BMidiLocalConsumer_Timeout; hook will be called at some point
|
||||
</para>
|
||||
|
||||
<para>
|
||||
This method asks the consumer thread to call the &BMidiLocalConsumer_Timeout; hook as soon as
|
||||
possible after the timeout expires. For every call to SetTimeout(), the
|
||||
&BMidiLocalConsumer_Timeout; hook is only called once. Note: the term "timeout" may be a little
|
||||
misleading; the hook will <emphasis>always</emphasis> be called, even if events are received
|
||||
in the mean time. Apparently, this facility is handy for dealing with early
|
||||
events.
|
||||
</para>
|
||||
|
||||
|
||||
<para>
|
||||
Note that the event thread blocks on the consumer's port as long as no events
|
||||
arrive. By default no timeout is set, and as a result the thread blocks
|
||||
forever. Your call to SetTimeout() doesn't change this. The new timeout value
|
||||
will go into effect the next time the thread tries to read from the port, i.e.
|
||||
after the first event has been received. If no event ever comes in, the
|
||||
&BMidiLocalConsumer_Timeout; hook will never be called. This also means that you cannot cancel a
|
||||
timeout once you have set it. To repeat, calling SetTimeout() only takes effect
|
||||
after at least one new event has been received.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Parameters:
|
||||
<itemizedlist>
|
||||
<listitem><para><parameter>when</parameter> An absolute time that's
|
||||
measured against the system clock.</para></listitem>
|
||||
<listitem><para><parameter>data</parameter> A pointer to a "cookie" that
|
||||
you can pass along to &BMidiLocalConsumer_Timeout;. The data is not copied, so
|
||||
you must ensure that the pointer remains valid until &BMidiLocalConsumer_Timeout; is
|
||||
called. You typically delete the data inside &BMidiLocalConsumer_Timeout;.</para></listitem>
|
||||
</itemizedlist>
|
||||
</para>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bmidilocalconsumer_timeout">
|
||||
<title>Timeout()</title>
|
||||
<methodsynopsis><modifier>virtual</modifier><void/><methodname>Timeout</methodname><methodparam><type>void *</type><parameter>data</parameter></methodparam></methodsynopsis>
|
||||
|
||||
<para>
|
||||
Hook function that is called per your own request.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
See Also <xref linkend="bmidilocalconsumer_settimeout" />
|
||||
</para>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bmidilocalconsumer_data">
|
||||
<title>Data()</title>
|
||||
<methodsynopsis><modifier>virtual</modifier><void/><methodname>Data</methodname><methodparam><type>uchar *</type><parameter>data</parameter></methodparam><methodparam><type>size_t</type><parameter>length</parameter></methodparam><methodparam><type>bool</type><parameter>atomic</parameter></methodparam><methodparam><type>bigtime_t</type><parameter>time</parameter></methodparam></methodsynopsis>
|
||||
|
||||
<para>
|
||||
Invoked when raw MIDI is received
|
||||
</para>
|
||||
|
||||
<para>
|
||||
What the default implementation of Data() does depends on the value of atomic.
|
||||
If atomic is true, the data received comprises a single MIDI event; i.e. one
|
||||
status byte followed by the appropriate number of data bytes and nothing else.
|
||||
In this case, Data() calls the event-specific hook function that corresponds to
|
||||
that status byte. This optimization is used by the Midi Kit to allow faster
|
||||
dispatch of events generated by the specific Spray functions from
|
||||
BMidiLocalProducer.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
If atomic is false, Data() ignores the MIDI event. If you want a consumer to
|
||||
handle non-atomic events, you have to override Data() and program this
|
||||
yourself. In that case, you probably also want to call the default
|
||||
implementation to handle the "normal" MIDI events.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Data() is rarely overridden, but you can override it if you want to. If you do,
|
||||
remember that the data buffer is owned by the Midi Kit. Do not attempt to
|
||||
modify or free it, lest you wish to be laughed at by other developers.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Parameters:
|
||||
<itemizedlist>
|
||||
<listitem><para><parameter>data</parameter> the MIDI event data</para></listitem>
|
||||
<listitem><para><parameter>length</parameter> byte size of the data buffer</para></listitem>
|
||||
<listitem><para><parameter>atomic</parameter> whether the data buffer contains
|
||||
a single complete MIDI event</para></listitem>
|
||||
<listitem><para><parameter>time</parameter> the requested performance time of the event</para></listitem>
|
||||
</itemizedlist>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
See Also <xref linkend="bmidilocalproducer_spraydata" />
|
||||
</para>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bmidilocalconsumer_noteoff">
|
||||
<title>NoteOff()</title>
|
||||
<methodsynopsis><modifier>virtual</modifier><void/><methodname>NoteOff</methodname><methodparam><type>uchar</type><parameter>channel</parameter></methodparam><methodparam><type>uchar</type><parameter>note</parameter></methodparam><methodparam><type>uchar</type><parameter>velocity</parameter></methodparam><methodparam><type>bigtime_t</type><parameter>time</parameter></methodparam></methodsynopsis>
|
||||
|
||||
<para>
|
||||
Invoked when a Note Off event is received
|
||||
</para>
|
||||
|
||||
<para>
|
||||
See Also <xref linkend="bmidilocalproducer_spraynoteoff" />
|
||||
</para>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bmidilocalconsumer_noteon">
|
||||
<title>NoteOn()</title>
|
||||
<methodsynopsis><modifier>virtual</modifier><void/><methodname>NoteOn</methodname><methodparam><type>uchar</type><parameter>channel</parameter></methodparam><methodparam><type>uchar</type><parameter>note</parameter></methodparam><methodparam><type>uchar</type><parameter>velocity</parameter></methodparam><methodparam><type>bigtime_t</type><parameter>time</parameter></methodparam></methodsynopsis>
|
||||
|
||||
<para>
|
||||
Invoked when a Note On event is received
|
||||
</para>
|
||||
|
||||
<para>
|
||||
See Also <xref linkend="bmidilocalproducer_spraynoteon" />
|
||||
</para>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bmidilocalconsumer_keypressure">
|
||||
<title>KeyPressure()</title>
|
||||
<methodsynopsis><modifier>virtual</modifier><void/><methodname>KeyPressure</methodname><methodparam><type>uchar</type><parameter>channel</parameter></methodparam><methodparam><type>uchar</type><parameter>note</parameter></methodparam><methodparam><type>uchar</type><parameter>pressure</parameter></methodparam><methodparam><type>bigtime_t</type><parameter>time</parameter></methodparam></methodsynopsis>
|
||||
|
||||
<para>
|
||||
Invoked when a Polyphonic Pressure (Aftertouch) event is received
|
||||
</para>
|
||||
|
||||
<para>
|
||||
See Also <xref linkend="bmidIlocalproducer_spraykeypressure"/>
|
||||
</para>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bmidilocalconsumer_controlchange">
|
||||
<title>ControlChange()</title>
|
||||
<methodsynopsis><modifier>virtual</modifier><void/><methodname>ControlChange</methodname><methodparam><type>uchar</type><parameter>channel</parameter></methodparam><methodparam><type>uchar</type><parameter>controlNumber</parameter></methodparam><methodparam><type>uchar</type><parameter>controlValue</parameter></methodparam><methodparam><type>bigtime_t</type><parameter>time</parameter></methodparam></methodsynopsis>
|
||||
|
||||
<para>
|
||||
Invoked when a Controller Change event is received
|
||||
</para>
|
||||
|
||||
<para>
|
||||
See Also <xref linkend="bmidilocalproducer_spraycontrolchange" />
|
||||
</para>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bmidilocalconsumer_programchange">
|
||||
<title>ProgramChange()</title>
|
||||
<methodsynopsis><modifier>virtual</modifier><void/><methodname>ProgramChange</methodname><methodparam><type>uchar</type><parameter>channel</parameter></methodparam><methodparam><type>uchar</type><parameter>programNumber</parameter></methodparam><methodparam><type>bigtime_t</type><parameter>time</parameter></methodparam></methodsynopsis>
|
||||
|
||||
<para>
|
||||
Invoked when a Program Change event is received
|
||||
</para>
|
||||
|
||||
<para>
|
||||
See Also <xref linkend="bmidilocalproducer_sprayprogramchange" />
|
||||
</para>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bmidilocalconsumer_channelpressure">
|
||||
<title>ChannelPressure()</title>
|
||||
<methodsynopsis><modifier>virtual</modifier><void/><methodname>ChannelPressure</methodname><methodparam><type>uchar</type><parameter>channel</parameter></methodparam><methodparam><type>uchar</type><parameter>pressure</parameter></methodparam><methodparam><type>bigtime_t</type><parameter>time</parameter></methodparam></methodsynopsis>
|
||||
|
||||
<para>
|
||||
Invoked when a Channel Pressure event is received
|
||||
</para>
|
||||
|
||||
<para>
|
||||
See Also <xref linkend="bmidilocalproducer_spraychannelpressure" />
|
||||
</para>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bmidilocalconsumer_pitchbend">
|
||||
<title>PitchBend()</title>
|
||||
<methodsynopsis><modifier>virtual</modifier><void/><methodname>PitchBend</methodname><methodparam><type>uchar</type><parameter>channel</parameter></methodparam><methodparam><type>uchar</type><parameter>lsb</parameter></methodparam><methodparam><type>uchar</type><parameter>msb</parameter></methodparam><methodparam><type>bigtime_t</type><parameter>time</parameter></methodparam></methodsynopsis>
|
||||
|
||||
<para>
|
||||
Invoked when a Pitch Bend event is received
|
||||
</para>
|
||||
|
||||
<para>
|
||||
See Also <xref linkend="bmidilocalproducer_spraypitchbend" />
|
||||
</para>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bmidilocalconsumer_systemexclusive">
|
||||
<title>SystemExclusive()</title>
|
||||
<methodsynopsis><modifier>virtual</modifier><void/><methodname>SystemExclusive</methodname><methodparam><type>void *</type><parameter>data</parameter></methodparam><methodparam><type>size_t</type><parameter>length</parameter></methodparam><methodparam><type>bigtime_t</type><parameter>time</parameter></methodparam></methodsynopsis>
|
||||
|
||||
<para>
|
||||
Invoked when a System Exclusive event is received
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The data does not include the sysex start and end control bytes (0xF0 and 0xF7),
|
||||
only the payload of the sysex message.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The data belongs to the Midi Kit and is only valid for the duration of this
|
||||
event. You may not modify or free it.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
See Also <xref linkend="bmidilocalproducer_spraysystemexclusive" />
|
||||
</para>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bmidilocalconsumer_systemcommon">
|
||||
<title>SystemCommon()</title>
|
||||
<methodsynopsis><modifier>virtual</modifier><void/><methodname>SystemCommon</methodname><methodparam><type>uchar</type><parameter>status</parameter></methodparam><methodparam><type>uchar</type><parameter>data1</parameter></methodparam><methodparam><type>uchar</type><parameter>data2</parameter></methodparam><methodparam><type>bigtime_t</type><parameter>time</parameter></methodparam></methodsynopsis>
|
||||
|
||||
<para>
|
||||
Invoked when a System Common event is received.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Not all data bytes are used for all common events. Unused bytes are set to 0.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
See Also <xref linkend="bmidilocalproducer_spraysystemcommon" />
|
||||
</para>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bmidilocalconsumer_systemrealtime">
|
||||
<title>SystemRealTime()</title>
|
||||
<methodsynopsis><modifier>virtual</modifier><void/><methodname>SystemRealTime</methodname><methodparam><type>uchar</type><parameter>status</parameter></methodparam><methodparam><type>bigtime_t</type><parameter>time</parameter></methodparam></methodsynopsis>
|
||||
|
||||
<para>
|
||||
Invoked when a Real Time event is received
|
||||
</para>
|
||||
|
||||
<para>
|
||||
See Also <xref linkend="bmidilocalproducer_spraysystemrealtime" />
|
||||
</para>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bmidilocalconsumer_tempochange">
|
||||
<title>TempoChange()</title>
|
||||
<methodsynopsis><modifier>virtual</modifier><void/><methodname>TempoChange</methodname><methodparam><type>int32</type><parameter>beatsPerMinute</parameter></methodparam><methodparam><type>bigtime_t</type><parameter>time</parameter></methodparam></methodsynopsis>
|
||||
|
||||
<para>
|
||||
Invoked when a Tempo Change event is received
|
||||
</para>
|
||||
|
||||
<para>
|
||||
See Also <xref linkend="bmidilocalproducer_spraytempochange" />
|
||||
</para>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bmidilocalconsumer_allnotesoff">
|
||||
<title>AllNotesOff()</title>
|
||||
<methodsynopsis><modifier>virtual</modifier><void/><methodname>AllNotesOff</methodname><methodparam><type>bool</type><parameter>justChannel</parameter></methodparam><methodparam><type>bigtime_t</type><parameter>time</parameter></methodparam></methodsynopsis>
|
||||
|
||||
<para>
|
||||
Not used
|
||||
</para>
|
||||
</sect3>
|
||||
</sect2>
|
||||
@@ -1,403 +0,0 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
|
||||
<sect2 id="bmidilocalproducer">
|
||||
<title>BMidiLocalProducer</title>
|
||||
|
||||
<para>
|
||||
You create a BMidiLocalProducer if you want your application to send MIDI
|
||||
events. You use the various spray functions to send events to all connected
|
||||
consumers. If no consumers are connected to the producer, any calls to the
|
||||
spray functions are ignored.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Most spray functions accept a channel argument. Even though MIDI channels are
|
||||
really numbered 1 through 16, the spray functions work with channels 0 through
|
||||
15. You can also specify the performance time for the event using the time
|
||||
argument. Specify 0 (or any time in the past) to perform the event "now", i.e.
|
||||
as soon as possible. You can also schedule events to be performed in the
|
||||
future, by passing a time such as system_time() + 5000000, which means 5
|
||||
seconds from now.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Unlike BMidiLocalConsumer, which should be subclassed almost always, you hardly
|
||||
ever need to derive a class from BMidiLocalProducer. The only reason for
|
||||
subclassing is when you need to know when the producer gets connected or
|
||||
disconnected.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Also unlike consumers, local producers have no thread of control directly
|
||||
associated with them. If you want to send out the MIDI events from a different
|
||||
thread, you will have to create one yourself.
|
||||
</para>
|
||||
|
||||
<sect3 id="bmidilocalproducer_bmidilocalproducer">
|
||||
<title>BMidiLocalProducer()</title>
|
||||
<methodsynopsis>
|
||||
<methodname>BMidiLocalProducer</methodname>
|
||||
<methodparam><modifier>const</modifier><type>char *</type><parameter>name</parameter><initializer>NULL</initializer></methodparam>
|
||||
</methodsynopsis>
|
||||
<para>
|
||||
Creates a new local producer endpoint.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The new endpoint is not visible to other applications until you Register() it.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
You can tell the constructor what the name of the new producer will be. If you
|
||||
pass NULL (or use the default argument), then the producer's name will be an
|
||||
empty string. It won't be NULL, since endpoint names cannot be NULL.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
There is no guarantee that the endpoint will be successfully created. For
|
||||
example, the Midi Server may not be running. Therefore, you should always call
|
||||
&BMidiEndpoint_IsValid; after creating a new endpoint to make sure that everything went okay.
|
||||
If not, &BMidiEndpoint_Release; the object to reclaim memory and abort gracefully.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<programlisting>
|
||||
BMidiLocalProducer *prod = new BMidiLocalProducer(...);
|
||||
if (!prod->IsValid())
|
||||
{
|
||||
prod->Release();
|
||||
...exit gracefully...
|
||||
}
|
||||
</programlisting>
|
||||
</para>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bmidilocalproducer_connected">
|
||||
<title>Connected()</title>
|
||||
<methodsynopsis><modifier>virtual</modifier><void/><methodname>Connected</methodname><methodparam><modifier>const</modifier><type>BMidiConsumer *</type><parameter>cons</parameter></methodparam></methodsynopsis>
|
||||
<para>
|
||||
Invoked when a new consumer is connected to this producer
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Although typical notifications (i.e. from BMidiRoster's "watching" facility)
|
||||
are only sent if it is some other app that is performing the operation,
|
||||
Connected() is also called if you are making the connection yourself.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
If you override this hook, you don't have to call the default implementation,
|
||||
because that does nothing.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<parameter>cons</parameter> The newly connected consumer. The reference count of the consumer
|
||||
object is not increased, so you should not Release() it. However, if you want
|
||||
to keep track of the consumer beyond this function, you should first Acquire()
|
||||
it, and Release() it when you are done.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
See Also <xref linkend="bmidilocalproducer_disconnected" />
|
||||
</para>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bmidilocalproducer_disconnected">
|
||||
<title>Disconnected()</title>
|
||||
<methodsynopsis><modifier>virtual</modifier><void/><methodname>Disconnected</methodname><methodparam><modifier>const</modifier><type>BMidiConsumer *</type><parameter>cons</parameter></methodparam></methodsynopsis>
|
||||
|
||||
<para>
|
||||
Invoked when a consumer is disconnected from this producer.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
See Also <xref linkend="bmidilocalproducer_connected" />
|
||||
</para>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bmidilocalproducer_spraydata">
|
||||
<title>SprayData()</title>
|
||||
<methodsynopsis><void/><methodname>SprayData</methodname><methodparam><type>void *</type><parameter>data</parameter></methodparam><methodparam><type>size_t</type><parameter>length</parameter></methodparam><methodparam><type>bool</type><parameter>atomic</parameter><initializer>false</initializer></methodparam><methodparam><type>bigtime_t</type><parameter>time</parameter><initializer>0</initializer></methodparam><modifier>const</modifier></methodsynopsis>
|
||||
|
||||
<para>
|
||||
Sends raw MIDI data downstream to all connected consumers
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Typically you won't have to call SprayData(); the other spray functions will do
|
||||
just fine. If you do call it, remember that you retain ownership of the data
|
||||
and that you are responsible for freeing it at some point. (Even though data is
|
||||
not declared const, the function does not change it.)
|
||||
</para>
|
||||
|
||||
<para>
|
||||
With atomic set to false, you can send a MIDI message in segments (perhaps for
|
||||
a large sysex dump). However, when you do this, you are on your own. The Midi
|
||||
Kit only tags the data as being non-atomic, but offers no additional support.
|
||||
The default implementation of BMidiLocalConsumer completely ignores such
|
||||
events. To handle non-atomic MIDI data, you should override the
|
||||
BMidiLocalConsumer::Data() hook and process the MIDI event yourself. All of
|
||||
BMidiLocalProducer's other spray functions always send atomic data.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Parameters:
|
||||
<itemizedlist>
|
||||
<listitem><para><parameter>data</parameter> the MIDI event data</para></listitem>
|
||||
<listitem><para><parameter>length</parameter> byte size of the data buffer</para></listitem>
|
||||
<listitem><para><parameter>atomic</parameter> whether the data buffer contains
|
||||
a single complete MIDI event</para></listitem>
|
||||
<listitem><para><parameter>time</parameter> the required performance time of the event</para></listitem>
|
||||
</itemizedlist>
|
||||
</para>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bmidilocalproducer_spraynoteoff">
|
||||
<title>SprayNoteOff()</title>
|
||||
<methodsynopsis><void/><methodname>SprayNoteOff</methodname><methodparam><type>uchar</type><parameter>channel</parameter></methodparam><methodparam><type>uchar</type><parameter>note</parameter></methodparam><methodparam><type>uchar</type><parameter>velocity</parameter></methodparam><methodparam><type>bigtime_t</type><parameter>time</parameter><initializer>0</initializer></methodparam><modifier>const</modifier></methodsynopsis>
|
||||
|
||||
<para>
|
||||
Sends a Note Off event to all connected consumers
|
||||
</para>
|
||||
|
||||
<para>
|
||||
See Also <xref linkend="bmidilocalconsumer_noteoff" />
|
||||
</para>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bmidilocalproducer_spraynoteon">
|
||||
<title>SprayNoteOn()</title>
|
||||
<methodsynopsis><void/><methodname>SprayNoteOn</methodname><methodparam><type>uchar</type><parameter>channel</parameter></methodparam><methodparam><type>uchar</type><parameter>note</parameter></methodparam><methodparam><type>uchar</type><parameter>velocity</parameter></methodparam><methodparam><type>bigtime_t</type><parameter>time</parameter><initializer>0</initializer></methodparam><modifier>const</modifier></methodsynopsis>
|
||||
|
||||
<para>
|
||||
Sends a Note On event to all connected consumers
|
||||
</para>
|
||||
|
||||
<para>
|
||||
See Also <xref linkend="bmidilocalconsumer_noteon" />
|
||||
</para>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bmidIlocalproducer_spraykeypressure">
|
||||
<title>SprayKeyPressure()</title>
|
||||
<methodsynopsis><void/><methodname>SprayKeyPressure</methodname><methodparam><type>uchar</type><parameter>channel</parameter></methodparam><methodparam><type>uchar</type><parameter>note</parameter></methodparam><methodparam><type>uchar</type><parameter>pressure</parameter></methodparam><methodparam><type>bigtime_t</type><parameter>time</parameter><initializer>0</initializer></methodparam><modifier>const</modifier></methodsynopsis>
|
||||
|
||||
<para>
|
||||
Sends a Polyphonic Pressure (Aftertouch) event to all connected
|
||||
consumers.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
See Also <xref linkend="bmidilocalconsumer_keypressure"/>
|
||||
</para>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bmidilocalproducer_spraycontrolchange">
|
||||
<title>SprayControlChange()</title>
|
||||
<methodsynopsis><void/><methodname>SprayControlChange</methodname><methodparam><type>uchar</type><parameter>channel</parameter></methodparam><methodparam><type>uchar</type><parameter>controlNumber</parameter></methodparam><methodparam><type>uchar</type><parameter>controlValue</parameter></methodparam><methodparam><type>bigtime_t</type><parameter>time</parameter><initializer>0</initializer></methodparam><modifier>const</modifier></methodsynopsis>
|
||||
|
||||
<para>
|
||||
Sends a Controller Change event to all connected consumers.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
See Also <xref linkend="midicontrollernumbers"/> and
|
||||
<xref linkend="bmidilocalconsumer_controlchange"/>
|
||||
</para>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bmidilocalproducer_sprayprogramchange">
|
||||
<title>SprayProgramChange()</title>
|
||||
<methodsynopsis><void/><methodname>SprayProgramChange</methodname><methodparam><type>uchar</type><parameter>channel</parameter></methodparam><methodparam><type>uchar</type><parameter>programNumber</parameter></methodparam><methodparam><type>bigtime_t</type><parameter>time</parameter><initializer>0</initializer></methodparam><modifier>const</modifier></methodsynopsis>
|
||||
|
||||
<para>
|
||||
Sends a Program Change event to all connected consumers
|
||||
</para>
|
||||
|
||||
<para>
|
||||
See Also <xref linkend="bmidilocalconsumer_programchange"/>
|
||||
</para>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bmidilocalproducer_spraychannelpressure">
|
||||
<title>SprayChannelPressure()</title>
|
||||
<methodsynopsis><void/><methodname>SprayChannelPressure</methodname><methodparam><type>uchar</type><parameter>channel</parameter></methodparam><methodparam><type>uchar</type><parameter>pressure</parameter></methodparam><methodparam><type>bigtime_t</type><parameter>time</parameter><initializer>0</initializer></methodparam><modifier>const</modifier></methodsynopsis>
|
||||
|
||||
<para>
|
||||
Sends a Channel Pressure event to all connected consumers
|
||||
</para>
|
||||
|
||||
<para>
|
||||
See also <xref linkend="bmidilocalconsumer_channelpressure"/>
|
||||
</para>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bmidilocalproducer_spraypitchbend">
|
||||
<title>SprayPitchBend()</title>
|
||||
<methodsynopsis><void/><methodname>SprayPitchBend</methodname><methodparam><type>uchar</type><parameter>channel</parameter></methodparam><methodparam><type>uchar</type><parameter>lsb</parameter></methodparam><methodparam><type>uchar</type><parameter>msb</parameter></methodparam><methodparam><type>bigtime_t</type><parameter>time</parameter><initializer>0</initializer></methodparam><modifier>const</modifier></methodsynopsis>
|
||||
|
||||
<para>
|
||||
Sends a Pitch Bend event to all connected consumers
|
||||
</para>
|
||||
|
||||
<para>
|
||||
See Also <xref linkend="bmidilocalproducer_spraypitchbend"/>
|
||||
</para>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bmidilocalproducer_spraysystemexclusive">
|
||||
<title>SpraySystemExclusive()</title>
|
||||
<methodsynopsis><void/><methodname>SpraySystemExclusive</methodname><methodparam><type>void *</type><parameter>data</parameter></methodparam><methodparam><type>size_t</type><parameter>length</parameter></methodparam><methodparam><type>bigtime_t</type><parameter>time</parameter><initializer>0</initializer></methodparam><modifier>const</modifier></methodsynopsis>
|
||||
|
||||
<para>
|
||||
Sends a System Exclusive event to all connected consumers
|
||||
</para>
|
||||
|
||||
<para>
|
||||
You retain ownership of the data and are responsible for freeing it. Even
|
||||
though data is not declared const, the function does not change it. Even though
|
||||
the amount of data may be quite large, this function always sends sysex
|
||||
messages as an atomic block of data.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
See Also <xref linkend="bmidilocalconsumer_systemexclusive"/>
|
||||
</para>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bmidilocalproducer_spraysystemcommon">
|
||||
<title>SpraySystemCommon()</title>
|
||||
<methodsynopsis><void/><methodname>SpraySystemCommon</methodname><methodparam><type>uchar</type><parameter>status</parameter></methodparam><methodparam><type>uchar</type><parameter>data1</parameter></methodparam><methodparam><type>uchar</type><parameter>data2</parameter></methodparam><methodparam><type>bigtime_t</type><parameter>time</parameter><initializer>0</initializer></methodparam><modifier>const</modifier></methodsynopsis>
|
||||
|
||||
<para>
|
||||
Sends a System Common event to the connected consumers
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The status byte must be one of the following:
|
||||
|
||||
<table id="midisystemcode">
|
||||
<title>System Status</title>
|
||||
<tgroup cols='3' align='left' colsep='1' rowsep='1'>
|
||||
<colspec colname="hexvalue"/>
|
||||
<colspec colname='constant'/>
|
||||
<colspec colname='value'/>
|
||||
<tbody>
|
||||
<row>
|
||||
<entry><constant>0xF1</constant></entry>
|
||||
<entry><constant>B_MIDI_TIME_CODE</constant></entry>
|
||||
<entry>data1 only</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><constant>0xF2</constant></entry>
|
||||
<entry><constant>B_SONG_POSITION</constant></entry>
|
||||
<entry>data1 and data2</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><constant>0xF3</constant></entry>
|
||||
<entry><constant>B_SONG_SELECT</constant>
|
||||
</entry><entry>data1 only</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><constant>0xF5</constant></entry>
|
||||
<entry><constant>B_CABLE_MESSAGE</constant></entry>
|
||||
<entry>data1 only</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><constant>0xF6</constant></entry>
|
||||
<entry><constant>B_TUNE_REQUEST</constant></entry>
|
||||
<entry>no data</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><constant>0xF7</constant></entry>
|
||||
<entry><constant>B_SYS_EX_END</constant></entry>
|
||||
<entry>no data</entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</table>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
See Also <xref linkend="bmidilocalconsumer_systemcommon"/>
|
||||
</para>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bmidilocalproducer_spraysystemrealtime">
|
||||
<title>SpraySystemRealTime()</title>
|
||||
<methodsynopsis><void/><methodname>SpraySystemRealTime</methodname><methodparam><type>uchar</type><parameter>status</parameter></methodparam><methodparam><type>bigtime_t</type><parameter>time</parameter><initializer>0</initializer></methodparam><modifier>const</modifier></methodsynopsis>
|
||||
|
||||
<para>
|
||||
Sends a Real Time event to the connected consumers
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The status byte must be one of the following:
|
||||
|
||||
<table id="midirealtimecode">
|
||||
<title>RealTime Status</title>
|
||||
<tgroup cols='2' align='left' colsep='1' rowsep='1'>
|
||||
<colspec colname="hexvalue"/>
|
||||
<colspec colname='constant'/>
|
||||
<colspec colname='value'/>
|
||||
<tbody>
|
||||
<row>
|
||||
<entry><constant>0xF8</constant></entry>
|
||||
<entry><constant>B_TIMING_CLOCK</constant></entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><constant>0xFA</constant></entry>
|
||||
<entry><constant>B_START</constant></entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><constant>0xFB</constant></entry>
|
||||
<entry><constant>B_CONTINUE</constant></entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><constant>0xFC</constant></entry>
|
||||
<entry><constant>B_STOP</constant></entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><constant>0xFE</constant></entry>
|
||||
<entry><constant>B_ACTIVE_SENSING</constant></entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><constant>0xFF</constant></entry>
|
||||
<entry><constant>B_SYSTEM_RESET</constant></entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</table>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Because of their high priority, the MIDI specification allows real time
|
||||
messages to "interleave" with other MIDI messages. A large sysex dump, for
|
||||
example, may be interrupted by a real time event. The Midi Kit, however,
|
||||
doesn't care. If you (or another producer) have just sent a big system
|
||||
exclusive to a consumer, any following real time message will simply have to
|
||||
wait until the consumer has dealt with the sysex.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
See Also <xref linkend="bmidilocalconsumer_systemrealtime"/>
|
||||
</para>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bmidilocalproducer_spraytempochange">
|
||||
<title>SprayTempoChange()</title>
|
||||
<methodsynopsis><void/><methodname>SprayTempoChange</methodname><methodparam><type>int32</type><parameter>beatsPerMinute</parameter></methodparam><methodparam><type>bigtime_t</type><parameter>time</parameter><initializer>0</initializer></methodparam><modifier>const</modifier></methodsynopsis>
|
||||
<para>
|
||||
Sends a Tempo Change event to the connected consumers.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
This kind of Tempo Change event is not really part of the MIDI spec, rather
|
||||
it is an extension from the SMF (Standard MIDI File) format.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
See Also <xref linkend="bmidilocalconsumer_tempochange"/>
|
||||
</para>
|
||||
</sect3>
|
||||
</sect2>
|
||||
@@ -1,140 +0,0 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
|
||||
<sect2 id="bmidiproducer">
|
||||
<title>BMidiProducer</title>
|
||||
|
||||
<para>
|
||||
Streams MIDI events to connected consumers.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
A producer is an object that generate a stream of MIDI events. Each producer
|
||||
has a list of &BMidiConsumer; objects to which it is connected, and may be asked
|
||||
to connect to or disconnect from a &BMidiConsumer;. A producer can spray its
|
||||
events to multiple consumers at the same time.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
A &BMidiProducer; either represents a local producer, i.e. a class extending from
|
||||
&BMidiLocalProducer;, or is a proxy for a remote object published by another app.
|
||||
</para>
|
||||
|
||||
<sect3 id="bmidiproducer_connect">
|
||||
<title>Connect()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>status_t</type>
|
||||
<methodname>Connect</methodname>
|
||||
<methodparam><modifier>const</modifier><type>BMidiConsumer *</type> <parameter>cons</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
|
||||
<para>
|
||||
Connects a consumer to this producer.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Establishes a connection between this producer and the specified consumer
|
||||
endpoint. From now on, any events that this producer sprays will be sent to
|
||||
that consumer. You may connect multiple consumers to a producer.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Returns <returnvalue>B_OK</returnvalue> on success, or an error code when the connection could not be
|
||||
established. If the consumer is a proxy for a remote object and that object no
|
||||
longer exists, Connect() returns B_ERROR. It also returns B_ERROR if you try to
|
||||
connect the same producer and consumer more than once.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
See Also &BMidiProducer_Disconnect;.
|
||||
</para>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bmidiproducer_disconnect">
|
||||
<title>Disconnect()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>status_t</type>
|
||||
<methodname>Disconnect</methodname>
|
||||
<methodparam><modifier>const</modifier><type>BMidiConsumer *</type> <parameter>cons</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
|
||||
<para>
|
||||
Disconnects a consumer from this producer.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Terminates the connection between this producer and the specified consumer
|
||||
endpoint. From now on, any events that this producer sprays no longer go to
|
||||
that consumer.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Returns <returnvalue>B_OK</returnvalue> on success, or an error code if there was no connection to break
|
||||
</para>
|
||||
|
||||
<para>
|
||||
See Also &BMidiProducer_Connect;.
|
||||
</para>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bmidiproducer_isconnected">
|
||||
<title>IsConnected()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>bool</type>
|
||||
<methodname>IsConnected</methodname>
|
||||
<methodparam><modifier>const</modifier><type>BMidiConsumer *</type> <parameter>cons</parameter></methodparam>
|
||||
<modifier>const</modifier>
|
||||
</methodsynopsis>
|
||||
|
||||
<para>
|
||||
Determines whether a consumer is connected to this producer.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
See Also &BMidiProducer_Connect; and
|
||||
&BMidiProducer_Disconnect;
|
||||
</para>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bmidiproducer_connections">
|
||||
<title>Connections()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>BList *</type>
|
||||
<methodname>Connections</methodname><void/>
|
||||
<modifier>const</modifier>
|
||||
</methodsynopsis>
|
||||
|
||||
<para>
|
||||
Returns a list with all connected consumers.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Returns a BList with pointers to &BMidiEndpoint; objects for all consumers that
|
||||
are connected to this producer. You can examine the contents of the list as
|
||||
follows:
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<programlisting>
|
||||
BList *list = prod->Connections();
|
||||
for (int32 t = 0; t < list-> CountItems(); ++t)
|
||||
{
|
||||
BMidiEndpoint *endp = (BMidiEndpoint *) list->ItemAt(t);
|
||||
...do stuff...
|
||||
endp->Release(); // yes, here too!
|
||||
}
|
||||
delete list;
|
||||
</programlisting>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Every time you call this function, a new BList is allocated. The caller (that
|
||||
is you) is responsible for freeing this list. The &BMidiEndpoint; objects in the
|
||||
list have their reference counts bumped, so you need to &BMidiEndpoint;::&BMidiEndpoint_Release; them before
|
||||
you delete the list or they will go all leaky on you.
|
||||
</para>
|
||||
</sect3>
|
||||
</sect2>
|
||||
@@ -1,555 +0,0 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
|
||||
<sect2 id="bmidiroster">
|
||||
<title>BMidiRoster</title>
|
||||
|
||||
<para>
|
||||
Interface to the system-wide Midi Roster
|
||||
</para>
|
||||
|
||||
<para>
|
||||
BMidiRoster allows you to find available MIDI consumer and producer objects.
|
||||
You can locate these objects using the iterative NextEndpoint(),
|
||||
NextProducer(), and NextConsumer() methods or by requesting notification
|
||||
messages to be sent with StartWatching(). Notification messages may contain
|
||||
object IDs which can be resolved using the FindEndpoint(), FindProducer(), and
|
||||
FindConsumer() methods.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The constructor and destructor of BMidiRoster are private, which means that you
|
||||
cannot create or delete your own BMidiRoster objects. Every application can
|
||||
have only one instance of BMidiRoster, which is automatically created the very
|
||||
first time you use a Midi Kit function.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
You can call BMidiRoster's functions like this:
|
||||
<programlisting>
|
||||
producer = FindProducer(someID);
|
||||
</programlisting>
|
||||
|
||||
Or using the slightly more annoying:
|
||||
<programlisting>
|
||||
BMidiRoster *roster = MidiRoster();
|
||||
if (roster != NULL)
|
||||
{
|
||||
producer = roster->FindProducer(someID);
|
||||
}
|
||||
</programlisting>
|
||||
</para>
|
||||
|
||||
<sect3 id="bmidiroster_nextendpoint">
|
||||
<title>NextEndpoint()</title>
|
||||
<methodsynopsis><modifier>static</modifier><type>BMidiEndpoint *</type><methodname>NextEndpoint</methodname><methodparam><type>int32 *</type><parameter>id</parameter></methodparam></methodsynopsis>
|
||||
|
||||
<para>
|
||||
Returns the next endpoint from the roster
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The "next endpoint" means: the endpoint with the ID that follows id. So if you
|
||||
set id to 3, the first possible endpoint it returns is endpoint 4. No endpoint
|
||||
can have ID 0, so passing 0 gives you the first endpoint. If you pass NULL
|
||||
instead of an ID, NextEndpoint() always returns NULL. When the function
|
||||
returns, it sets id to the ID of the endpoint that was found. If no more
|
||||
endpoints exist, NextEndpoint() returns NULL and id is not changed.
|
||||
NextEndpoint() does <emphasis>not</emphasis> return locally created endpoints, even if they
|
||||
are &BMidiEndpoint_Register;'ed.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Usage example:
|
||||
<programlisting>
|
||||
int32 id = 0;
|
||||
BMidiEndpoint *endp;
|
||||
while ((endp = NextEndpoint(&id)) != NULL)
|
||||
{
|
||||
...do something with endpoint ...
|
||||
endp->Release(); // don't forget!
|
||||
}
|
||||
</programlisting>
|
||||
</para>
|
||||
|
||||
<warning><para>
|
||||
Remember that NextEndpoint() bumps the endpoint's reference count, so you
|
||||
should always BMidiEndpoint::Release() it when you are
|
||||
done.
|
||||
</para></warning>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bmidiroster_nextproducer">
|
||||
<title>NextProducer()</title>
|
||||
<methodsynopsis><modifier>static</modifier><type>BMidiProducer *</type><methodname>NextProducer</methodname><methodparam><type>int32 *</type><parameter>id</parameter></methodparam></methodsynopsis>
|
||||
|
||||
<para>
|
||||
Returns the next producer from the roster
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Like &BMidiRoster_NextEndpoint;, but only returns producer endpoints.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
See Also <xref linkend="bmidiroster_nextconsumer"/> and
|
||||
<xref linkend="bmidiroster_nextendpoint"/>.
|
||||
</para>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bmidiroster_nextconsumer">
|
||||
<title>NextConsumer()</title>
|
||||
<methodsynopsis><modifier>static</modifier><type>BMidiConsumer *</type><methodname>NextConsumer</methodname><methodparam><type>int32 *</type><parameter>id</parameter></methodparam></methodsynopsis>
|
||||
|
||||
<para>
|
||||
Returns the next consumer from the roster
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Like &BMidiRoster_NextEndpoint;, but only returns consumer endpoints.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
See Also <xref linkend="bmidiroster_nextproducer"/> and
|
||||
<xref linkend="bmidiroster_nextendpoint"/>.
|
||||
</para>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bmidiroster_findendpoint">
|
||||
<title>FindEndpoint()</title>
|
||||
<methodsynopsis><modifier>static</modifier><type>BMidiEndpoint *</type><methodname>FindEndpoint</methodname><methodparam><type>int32</type><parameter>id</parameter></methodparam><methodparam><type>bool</type><parameter>localOnly</parameter><initializer>false</initializer></methodparam></methodsynopsis>
|
||||
|
||||
<para>
|
||||
Returns the endpoint with the specified ID
|
||||
</para>
|
||||
|
||||
<para>
|
||||
FindEndpoint() will always find <emphasis>any</emphasis> local endpoints created by this
|
||||
application; they do not have to be published with &BMidiRoster_Register; first. If
|
||||
localOnly is false, FindEndpoint() also looks at remote endpoints, otherwise
|
||||
only local endpoints will be resolved. Returns NULL if no such endpoint could
|
||||
be found.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
You should use a dynamic_cast to convert the BMidiEndpoint into a producer or
|
||||
consumer:
|
||||
</para>
|
||||
|
||||
<para><programlisting>
|
||||
BMidiEndpoint *endp = ...;
|
||||
BMidiProducer *prod = NULL;
|
||||
BMidiConsumer *cons = NULL;
|
||||
|
||||
if (endp->IsProducer())
|
||||
{
|
||||
prod = dynamic_cast<BMidiProducer *>(endp);
|
||||
}
|
||||
else if (endp->IsConsumer())
|
||||
{
|
||||
cons = dynamic_cast<BMidiConsumer *>(endp);
|
||||
}
|
||||
</programlisting></para>
|
||||
|
||||
<para>
|
||||
Remember that FindEndpoint() increments the endpoint's reference count, so you
|
||||
should always &BMidiEndpoint_Release; an endpoint
|
||||
when you are done with it:
|
||||
<programlisting>
|
||||
BMidiEndpoint *endp = FindEndpoint(someID);
|
||||
if (endp != NULL)
|
||||
{
|
||||
...do stuff with the endpoint...
|
||||
endp->Release();
|
||||
}
|
||||
</programlisting>
|
||||
</para>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bmidiroster_findproducer">
|
||||
<title>FindProducer()</title>
|
||||
<methodsynopsis><modifier>static</modifier><type>BMidiProducer *</type><methodname>FindProducer</methodname><methodparam><type>int32</type><parameter>id</parameter></methodparam><methodparam><type>bool</type><parameter>localOnly</parameter><initializer>false</initializer></methodparam></methodsynopsis>
|
||||
|
||||
<para>
|
||||
Finds the producer with the specified ID
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Like &BMidiRoster_FindEndpoint;, but only looks for producer endpoints. Returns NULL if no
|
||||
endpoint with that ID exists, or if that endpoint is not a producer.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
See Also <xref linkend="bmidiroster_findconsumer"/> and
|
||||
<xref linkend="bmidiroster_findendpoint"/>.
|
||||
</para>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bmidiroster_findconsumer">
|
||||
<title>FindConsumer()</title>
|
||||
<methodsynopsis><modifier>static</modifier><type>BMidiConsumer *</type><methodname>FindConsumer</methodname><methodparam><type>int32</type><parameter>id</parameter></methodparam><methodparam><type>bool</type><parameter>localOnly</parameter><initializer>false</initializer></methodparam></methodsynopsis>
|
||||
|
||||
<para>
|
||||
Finds the consumer with the specified ID
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Like &BMidiRoster_FindEndpoint;, but only looks for consumer endpoints. Returns NULL if no
|
||||
endpoint with that ID exists, or if that endpoint is not a consumer.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
See Also <xref linkend="bmidiroster_findproducer"/> and
|
||||
<xref linkend="bmidiroster_findendpoint"/>.
|
||||
</para>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bmidiroster_startwatching">
|
||||
<title>StartWatching()</title>
|
||||
<methodsynopsis><modifier>static</modifier><void/><methodname>StartWatching</methodname><methodparam><modifier>const</modifier><type>BMessenger *</type><parameter>msngr</parameter></methodparam></methodsynopsis>
|
||||
|
||||
<para>
|
||||
Start receiving notifications from the Midi Roster
|
||||
</para>
|
||||
|
||||
<para>
|
||||
When you start watching, BMidiRoster sends you notifications for all currently
|
||||
<emphasis>published</emphasis> <emphasis>remote</emphasis> endpoints, and all the current connections
|
||||
between them. (At this point, BMidiRoster does not let you know about
|
||||
connections between unpublished endpoints, nor does it tell you anything about
|
||||
your local endpoints, even though they may be published.)
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Thereafter, you'll receive notifications any time something important happens
|
||||
to an object. The application that performs these operations is itself not
|
||||
notified. The assumption here is that you already know about these changes,
|
||||
because you are the one that is performing them.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The notifications are BMessages with code B_MIDI_EVENT. You specify the
|
||||
BMessenger that will be used to send these messages. Each message contains a
|
||||
field called be:op that describes the type of notification.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The "registered" and "unregistered" notifications are sent when a remote
|
||||
endpoint Register()'s or Unregister()'s, respectively. You don't receive these
|
||||
notifications when you register or unregister your local endpoints, but the
|
||||
other apps will.
|
||||
<table id="bmidirostertable1">
|
||||
<title>B_MIDI_REGISTERED message structure</title>
|
||||
<tgroup cols='3' align='left' colsep='1' rowsep='1'>
|
||||
<colspec colname="label"/>
|
||||
<colspec colname='type'/>
|
||||
<colspec colname='description'/>
|
||||
<tbody>
|
||||
<row>
|
||||
<entry><constant>be:op</constant></entry>
|
||||
<entry><constant>int32</constant></entry>
|
||||
<entry><constant>B_MIDI_REGISTERED</constant></entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry><constant>be:id</constant></entry>
|
||||
<entry><constant>int32</constant></entry>
|
||||
<entry>ID of the endpoint</entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry><constant>be:type</constant></entry>
|
||||
<entry><constant>string</constant></entry>
|
||||
<entry>"producer" or "consumer"</entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</table>
|
||||
|
||||
<table id="bmidirostertable2">
|
||||
<title>B_MIDI_UNREGISTERED message structure</title>
|
||||
<tgroup cols='3' align='left' colsep='1' rowsep='1'>
|
||||
<colspec colname="label"/>
|
||||
<colspec colname='type'/>
|
||||
<colspec colname='description'/>
|
||||
<tbody>
|
||||
<row>
|
||||
<entry><constant>be:op</constant></entry>
|
||||
<entry><constant>int32</constant></entry>
|
||||
<entry><constant>B_MIDI_UNREGISTERED</constant></entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry><constant>be:id</constant></entry>
|
||||
<entry><constant>int32</constant></entry>
|
||||
<entry>ID of the endpoint</entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry><constant>be:type</constant></entry>
|
||||
<entry><constant>string</constant></entry>
|
||||
<entry>"producer" or "consumer"</entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</table>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The "connected" and "disconnected" notifications are sent when a consumer
|
||||
&BMidiProducer_Connect;'s to a producer, or when they
|
||||
&BMidiProducer_Disconnect;. You will receive these
|
||||
notifications when <emphasis>any</emphasis> two endpoints connect or disconnect, even if they
|
||||
are not published. (The purpose of which is debatable.) You won't receive the
|
||||
notifications if you are the one making the connection, even if both endpoints
|
||||
are remote. You <emphasis>will</emphasis> be notified when another app connects one of your
|
||||
published endpoints.
|
||||
|
||||
<table id="bmidirostertable3">
|
||||
<title>B_MIDI_CONNECTED message structure</title>
|
||||
<tgroup cols='3' align='left' colsep='1' rowsep='1'>
|
||||
<colspec colname="label"/>
|
||||
<colspec colname='type'/>
|
||||
<colspec colname='description'/>
|
||||
<tbody>
|
||||
<row>
|
||||
<entry><constant>be:op</constant></entry>
|
||||
<entry><constant>int32</constant></entry><entry>
|
||||
<constant>B_MIDI_CONNECTED</constant></entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry><constant>be:producer</constant></entry>
|
||||
<entry><constant>int32</constant></entry>
|
||||
<entry>ID of the connector</entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry><constant>be:consumer</constant></entry>
|
||||
<entry><constant>int32</constant></entry>
|
||||
<entry>ID of the connectee</entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</table>
|
||||
|
||||
<table id="bmidirostertable4">
|
||||
<title>B_MIDI_DISCONNECTED message structure</title>
|
||||
<tgroup cols='3' align='left' colsep='1' rowsep='1'>
|
||||
<colspec colname="label"/>
|
||||
<colspec colname='type'/>
|
||||
<colspec colname='description'/>
|
||||
<tbody>
|
||||
<row>
|
||||
<entry><constant>be:op</constant></entry>
|
||||
<entry><constant>int32</constant></entry>
|
||||
<entry><constant>B_MIDI_DISCONNECTED</constant></entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry><constant>be:producer</constant></entry>
|
||||
<entry><constant>int32</constant></entry>
|
||||
<entry>ID of the connector</entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry><constant>be:consumer</constant></entry>
|
||||
<entry><constant>int32</constant></entry>
|
||||
<entry>ID of the connectee</entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</table>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The following notifications are sent when an endpoint's attributes are changed.
|
||||
You receive these notifications only if another application is changing one of
|
||||
its published endpoints.
|
||||
|
||||
<table id="bmidirostertable5">
|
||||
<title>B_MIDI_CHANGED_NAME message structure</title>
|
||||
<tgroup cols='3' align='left' colsep='1' rowsep='1'>
|
||||
<colspec colname="label"/>
|
||||
<colspec colname='type'/>
|
||||
<colspec colname='description'/>
|
||||
<tbody>
|
||||
<row>
|
||||
<entry><constant>be:op</constant></entry>
|
||||
<entry><constant>int32</constant></entry>
|
||||
<entry><constant>B_MIDI_CHANGED_NAME</constant></entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry><constant>be:id</constant></entry>
|
||||
<entry><constant>int32</constant></entry>
|
||||
<entry><constant>ID of the endpoint</constant></entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry><constant>be:type</constant></entry>
|
||||
<entry><constant>string</constant></entry>
|
||||
<entry>"producer" or "consumer"</entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry><constant>be:name</constant></entry>
|
||||
<entry><constant>string</constant></entry>
|
||||
<entry>the endpoint's new name></entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</table>
|
||||
|
||||
<table id="bmidirostertable6">
|
||||
<title>B_MIDI_CHANGED_LATENCY message structure</title>
|
||||
<tgroup cols='3' align='left' colsep='1' rowsep='1'>
|
||||
<colspec colname="label"/>
|
||||
<colspec colname='type'/>
|
||||
<colspec colname='description'/>
|
||||
<tbody>
|
||||
<row>
|
||||
<entry><constant>be:op</constant></entry>
|
||||
<entry><constant>int32</constant></entry>
|
||||
<entry><constant>B_MIDI_CHANGED_LATENCY</constant></entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry><constant>be:id</constant></entry>
|
||||
<entry><constant>int32</constant></entry>
|
||||
<entry>ID of the endpoint</entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry><constant>be:type</constant></entry>
|
||||
<entry><constant>string</constant></entry>
|
||||
<entry>"producer" or "consumer"</entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry><constant>be:latency</constant></entry>
|
||||
<entry><constant>int64</constant></entry>
|
||||
<entry>the new latency (microseconds)</entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</table>
|
||||
|
||||
<table id="bmidirostertable7">
|
||||
<title>B_MIDI_CHANGED_PROPERTIES message structure</title>
|
||||
<tgroup cols='3' align='left' colsep='1' rowsep='1'>
|
||||
<colspec colname="label"/>
|
||||
<colspec colname='type'/>
|
||||
<colspec colname='description'/>
|
||||
<tbody>
|
||||
<row>
|
||||
<entry><constant>be:op</constant></entry>
|
||||
<entry><constant>int32</constant></entry>
|
||||
<entry><constant>B_MIDI_CHANGED_PROPERTIES</constant></entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry><constant>be:id</constant></entry>
|
||||
<entry><constant>int32</constant></entry>
|
||||
<entry>ID of the endpoint</entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry><constant>be:type</constant></entry>
|
||||
<entry><constant>string</constant></entry>
|
||||
<entry>"producer" or "consumer"</entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry><constant>be:properties</constant></entry>
|
||||
<entry><constant>BMessage</constant></entry>
|
||||
<entry>the new properties</entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</table>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Typical usage example:
|
||||
<programlisting>
|
||||
void MyView::AttachedToWindow()
|
||||
{
|
||||
BMessenger msgr(this);
|
||||
StartWatching(&msgr);
|
||||
}
|
||||
|
||||
void MyView::MessageReceived(BMessage *msg)
|
||||
{
|
||||
switch (msg->what)
|
||||
{
|
||||
case B_MIDI_EVENT:
|
||||
HandleMidiEvent(msg);
|
||||
break;
|
||||
default:
|
||||
super::MessageReceived(msg);
|
||||
break;
|
||||
}
|
||||
}
|
||||
</programlisting>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
See Also <link linkend="bmidiop">"The possible be:op codes (BMidiOp)"</link>.
|
||||
</para>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bmidiroster_stopwatching">
|
||||
<title>StopWatching()</title>
|
||||
<methodsynopsis><modifier>static</modifier><void/><methodname>StopWatching</methodname><void/></methodsynopsis>
|
||||
|
||||
<para>
|
||||
Stop receiving notifications from the Midi Roster
|
||||
</para>
|
||||
|
||||
<para>
|
||||
See Also <xref linkend="bmidiroster_startwatching"/>
|
||||
</para>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bmidiroster_register">
|
||||
<title>Register()</title>
|
||||
<methodsynopsis><modifier>static</modifier><type>status_t</type><methodname>Register</methodname><methodparam><type>BMidiEndpoint *</type><parameter>endp</parameter></methodparam></methodsynopsis>
|
||||
|
||||
<para>
|
||||
Publishes an endpoint to other applications
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Calls BMidiEndpoint's BMidiEndpoint::Register()
|
||||
method to publish an endpoint, which makes it visible to other applications.
|
||||
</para>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bmidiroster_unregister">
|
||||
<title>Unregister()</title>
|
||||
<methodsynopsis><modifier>static</modifier><type>status_t</type><methodname>Unregister</methodname><methodparam><type>BMidiEndpoint *</type><parameter>endp</parameter></methodparam></methodsynopsis>
|
||||
|
||||
<para>
|
||||
Hides an endpoint from other applications
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Calls BMidiEndpoint's BMidiEndpoint::Unregister()
|
||||
method to hide a previously published endpoint from other applications
|
||||
</para>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bmidiroster_midiroster">
|
||||
<title>MidiRoster()</title>
|
||||
<methodsynopsis><modifier>static</modifier><type>BMidiRoster *</type><methodname>MidiRoster</methodname><void/></methodsynopsis>
|
||||
|
||||
<para>
|
||||
Returns a pointer to the only instance of BMidiRoster
|
||||
</para>
|
||||
|
||||
<para>
|
||||
There is no real reason to use this function, since all BMidiRoster's public
|
||||
function are static.
|
||||
</para>
|
||||
</sect3>
|
||||
</sect2>
|
||||
@@ -1,11 +0,0 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
|
||||
<chapter id="st-midikit">
|
||||
<title>The Midi Kit</title>
|
||||
|
||||
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="midi/intro.xml" />
|
||||
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="midi/midi1.xml" />
|
||||
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="midi/midi2.xml" />
|
||||
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="midi/midi2api.xml" />
|
||||
</chapter>
|
||||
|
||||
@@ -1,13 +0,0 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
||||
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
|
||||
|
||||
]>
|
||||
|
||||
<sect1 id="network-intro">
|
||||
<title>Introduction</title>
|
||||
|
||||
<para> The <emphasis>Network Kit</emphasis> encompasses all user network functionality in Haiku, providing both the standard UNIX/POSIX socket implementation along with a number of convenience classes for simple buffering, address operations and endpoint manipulation.
|
||||
</para>
|
||||
</sect1>
|
||||
|
||||
@@ -1,8 +0,0 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
|
||||
<chapter id="st-networkkit">
|
||||
<title>The Network Kit</title>
|
||||
|
||||
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="network/intro.xml" />
|
||||
</chapter>
|
||||
|
||||
@@ -1,14 +0,0 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
||||
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
|
||||
|
||||
]>
|
||||
|
||||
<sect1 id="opengl-intro">
|
||||
<title>Introduction</title>
|
||||
|
||||
<para>
|
||||
The <emphasis>OpenGL Kit</emphasis> contains the Haiku OpenGL bindings and the BView subclass BGLView which manages the hardware interface and GL contexts.
|
||||
</para>
|
||||
</sect1>
|
||||
|
||||
@@ -1,8 +0,0 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
|
||||
<chapter id="st-openglkit">
|
||||
<title>The OpenGL Kit</title>
|
||||
|
||||
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="opengl/intro.xml" />
|
||||
</chapter>
|
||||
|
||||
@@ -1,19 +0,0 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
||||
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
|
||||
|
||||
]>
|
||||
|
||||
<sect1 id="storage-intro">
|
||||
<title>Introduction</title>
|
||||
|
||||
<para>
|
||||
The <emphasis>Storage Kit</emphasis> deals with the manipulation, retrieval and creation of filesystem objects. This is enabled by the Haiku implementation of the POSIX filesystem functions (written in C) and a collection of C++ classes which are concerned with areas such as:
|
||||
<itemizedlist>
|
||||
<listitem><para> Entries/nodes </para></listitem>
|
||||
<listitem><para> Volumes </para></listitem>
|
||||
<listitem><para> Queries/Indices </para></listitem>
|
||||
<listitem><para> Utility classes </para></listitem>
|
||||
</itemizedlist>
|
||||
</para>
|
||||
</sect1>
|
||||
@@ -1,8 +0,0 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
|
||||
<chapter id="st-storagekit">
|
||||
<title>The Storage Kit</title>
|
||||
|
||||
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="storage/intro.xml" />
|
||||
</chapter>
|
||||
|
||||
@@ -1,60 +0,0 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
|
||||
<sect2 id="barchivable">
|
||||
<title>BArchivable</title>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem><para><emphasis>Derived from:</emphasis> none</para></listitem>
|
||||
<listitem><para><emphasis>Declared in:</emphasis> <filename>os/support/Archivable.h</filename></para></listitem>
|
||||
<listitem><para><emphasis>Library:</emphasis> <filename>libbe.so</filename></para></listitem>
|
||||
</itemizedlist>
|
||||
|
||||
<para><classname>BArchivable</classname> works on archiving and unarchiving BMessages.</para>
|
||||
|
||||
<bridgehead renderas="sect2">Constructors and Destructors</bridgehead>
|
||||
<sect3 id="barchivable_constructor">
|
||||
<title>BArchivable()</title>
|
||||
|
||||
<constructorsynopsis>
|
||||
<methodname>BArchivable</methodname>
|
||||
</constructorsynopsis>
|
||||
|
||||
<constructorsynopsis>
|
||||
<methodname>BArchivable</methodname>
|
||||
<methodparam><type>BMessage *</type><parameter>from</parameter></methodparam>
|
||||
</constructorsynopsis>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="barchivable_destructor">
|
||||
<title>~BArchivable()</title>
|
||||
|
||||
<destructorsynopsis>
|
||||
<methodname>~BArchivable</methodname>
|
||||
</destructorsynopsis>
|
||||
</sect3>
|
||||
|
||||
<bridgehead renderas="sect2">Static Functions</bridgehead>
|
||||
<sect3 id="barchivable_instantiate">
|
||||
<title>Instantiate()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<modifier>static</modifier><type>BArchivable *</type><methodname>Instatiate</methodname>
|
||||
<methodparam><type>BMessage *</type><parameter>from</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
</sect3>
|
||||
|
||||
<bridgehead renderas="sect2">Member Functions</bridgehead>
|
||||
<sect3 id="archive">
|
||||
<title>Archive()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<modifier>virtual</modifier><type>status_t</type><methodname>Archive</methodname>
|
||||
<methodparam><type>BMessage *</type><parameter>into</parameter></methodparam>
|
||||
<methodparam><type>bool</type><parameter>deep</parameter><initializer>true</initializer></methodparam>
|
||||
<modifier>const</modifier>
|
||||
</methodsynopsis>
|
||||
</sect3>
|
||||
</sect2>
|
||||
|
||||
|
||||
|
||||
@@ -1,50 +0,0 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
|
||||
<sect2 id="bautolock">
|
||||
<title>BAutolock</title>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem><para><emphasis>Derived from:</emphasis> none</para></listitem>
|
||||
<listitem><para><emphasis>Declared in:</emphasis> <filename>os/support/AutoLock.h</filename></para></listitem>
|
||||
<listitem><para><emphasis>Library:</emphasis> <filename>libbe.so</filename></para></listitem>
|
||||
</itemizedlist>
|
||||
|
||||
<para><classname>BAutolock</classname> implements easy locking and unlocking using a <link linkend="blocker">BLocker</link> or a <classname>BLooper</classname> object.</para>
|
||||
|
||||
<bridgehead renderas="sect2">Constructors and Destructors</bridgehead>
|
||||
<sect3 id="bautolock_constructor">
|
||||
<title>BAutolock()</title>
|
||||
|
||||
<constructorsynopsis>
|
||||
<modifier>inline</modifier><methodname>BAutolock</methodname>
|
||||
<methodparam><type>BLooper *</type><parameter>looper</parameter></methodparam>
|
||||
</constructorsynopsis>
|
||||
|
||||
<constructorsynopsis>
|
||||
<modifier>inline</modifier><methodname>BAutolock</methodname>
|
||||
<methodparam><type>BLocker *</type><parameter>locker</parameter></methodparam>
|
||||
</constructorsynopsis>
|
||||
|
||||
<constructorsynopsis>
|
||||
<modifier>inline</modifier><methodname>BAutolock</methodname>
|
||||
<methodparam><type>BLocker &</type><parameter>locker</parameter></methodparam>
|
||||
</constructorsynopsis>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bautolock_destructor">
|
||||
<title>~BAutoLock()</title>
|
||||
|
||||
<destructorsynopsis>
|
||||
<modifier>inline</modifier><methodname>~BAutolock</methodname>
|
||||
</destructorsynopsis>
|
||||
</sect3>
|
||||
|
||||
<bridgehead renderas="sect2">Member Functions</bridgehead>
|
||||
<sect3 id="bautolock_islocked">
|
||||
<title>IsLocked()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>bool</type><methodname>IsLocked</methodname>
|
||||
</methodsynopsis>
|
||||
</sect3>
|
||||
</sect2>
|
||||
@@ -1,53 +0,0 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
|
||||
<sect2 id="bblockcache">
|
||||
<title>BBlockCache</title>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem><para><emphasis>Derived from:</emphasis> none</para></listitem>
|
||||
<listitem><para><emphasis>Declared in:</emphasis> <filename>os/support/BlockCache.h</filename></para></listitem>
|
||||
<listitem><para><emphasis>Library:</emphasis> <filename>libbe.so</filename></para></listitem>
|
||||
</itemizedlist>
|
||||
|
||||
<para><classname>BBlockCache</classname> is used to manage a pool of memory blocks.</para>
|
||||
|
||||
<bridgehead renderas="sect2">Constructors and Destructors</bridgehead>
|
||||
<sect3 id="bblockcache_constructor">
|
||||
<title>BBlockCache()</title>
|
||||
|
||||
<constructorsynopsis>
|
||||
<methodname>BBlockCache</methodname>
|
||||
<methodparam><type>uint32</type><parameter>blockCount</parameter></methodparam>
|
||||
<methodparam><type>size_t</type><parameter>blockSize</parameter></methodparam>
|
||||
<methodparam><type>uitn32</type><parameter>allocationType</parameter></methodparam>
|
||||
</constructorsynopsis>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="blist_destructor">
|
||||
<title>~BBlockCache()</title>
|
||||
|
||||
<destructorsynopsis>
|
||||
<methodname>~BBlockCache</methodname>
|
||||
</destructorsynopsis>
|
||||
</sect3>
|
||||
|
||||
<bridgehead renderas="sect2">Member Functions</bridgehead>
|
||||
|
||||
<sect3 id="bblockcache_get">
|
||||
<title>Get()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>void *</type><methodname>Get</methodname>
|
||||
<methodparam><type>size_t</type><parameter>blockSize</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bblockcache_save">
|
||||
<title>Save()</title>
|
||||
<methodsynopsis>
|
||||
<void/><methodname>Save</methodname>
|
||||
<methodparam><type>void *</type><parameter>pointer</parameter></methodparam>
|
||||
<methodparam><type>size_t</type><parameter>blockSize</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
</sect3>
|
||||
</sect2>
|
||||
@@ -1,53 +0,0 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
|
||||
<sect2 id="bdataio">
|
||||
<title>BDataIO</title>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem><para><emphasis>Derived from:</emphasis> none</para></listitem>
|
||||
<listitem><para><emphasis>Declared in:</emphasis> <filename>os/support/DataIO.h</filename></para></listitem>
|
||||
<listitem><para><emphasis>Library:</emphasis> <filename>libbe.so</filename></para></listitem>
|
||||
</itemizedlist>
|
||||
|
||||
<para><classname>BDataIO</classname> provides a base interface for reading and writing data.</para>
|
||||
|
||||
<bridgehead renderas="sect2">Constructors and Destructors</bridgehead>
|
||||
<sect3 id="bdataio_constructor">
|
||||
<title>BDataIO()</title>
|
||||
|
||||
<constructorsynopsis>
|
||||
<methodname>BDataIO</methodname>
|
||||
</constructorsynopsis>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bdataio_destructor">
|
||||
<title>~BDataIO()</title>
|
||||
|
||||
<destructorsynopsis>
|
||||
<modifier>virtual</modifier><methodname>~BDataIO</methodname>
|
||||
</destructorsynopsis>
|
||||
</sect3>
|
||||
|
||||
<bridgehead renderas="sect2">Member Functions</bridgehead>
|
||||
<sect3 id="bdataio_read">
|
||||
<title>Read()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<modifier>virtual</modifier><type>ssize_t</type><methodname>Read</methodname>
|
||||
<methodparam><type>void *</type><parameter>buffer</parameter></methodparam>
|
||||
<methodparam><type>size_t</type><parameter>size</parameter></methodparam>
|
||||
<modifier>= 0</modifier>
|
||||
</methodsynopsis>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bdataio_write">
|
||||
<title>Write()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<modifier>virtual</modifier><type>ssize_t</type><methodname>Write</methodname>
|
||||
<methodparam><modifier>const</modifier><type>void *</type><parameter>buffer</parameter></methodparam>
|
||||
<methodparam><type>size_t</type><parameter>size</parameter></methodparam>
|
||||
<modifier>= 0</modifier>
|
||||
</methodsynopsis>
|
||||
</sect3>
|
||||
</sect2>
|
||||
@@ -1,82 +0,0 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
|
||||
<sect2 id="bflattenable">
|
||||
<title>BFlattenable</title>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem><para><emphasis>Derived from:</emphasis> none</para></listitem>
|
||||
<listitem><para><emphasis>Declared in:</emphasis> <filename>os/support/Flattenable.h</filename></para></listitem>
|
||||
<listitem><para><emphasis>Library:</emphasis> <filename>libbe.so</filename></para></listitem>
|
||||
</itemizedlist>
|
||||
|
||||
<para><classname>BFlattenable</classname> is a protocol that classes can implement so that they can be written to a stream of bytes.</para>
|
||||
|
||||
<bridgehead renderas="sect2">Constructors and Destructors</bridgehead>
|
||||
<sect3 id="bflattenable_destructor">
|
||||
<title>~BFlattenable</title>
|
||||
|
||||
<destructorsynopsis>
|
||||
<modifier>virtual</modifier><methodname>~BFlattenable</methodname>
|
||||
</destructorsynopsis>
|
||||
</sect3>
|
||||
|
||||
<bridgehead renderas="sect2">Member Functions</bridgehead>
|
||||
<sect3 id="bflattenable_allowstypecode">
|
||||
<title>AllowsTypeCode()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<modifier>virtual</modifier><type>bool</type><methodname>AllowsTypeCode</methodname>
|
||||
<methodparam><type>type_code</type><parameter>code</parameter></methodparam>
|
||||
<modifier>= 0</modifier>
|
||||
</methodsynopsis>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bflattenable_flatten">
|
||||
<title>Flatten()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<modifier>virtual</modifier><type>status_t</type><methodname>Flatten</methodname>
|
||||
<methodparam><type>void *</type><parameter>buffer</parameter></methodparam>
|
||||
<methodparam><type>ssize_t</type><parameter>size</parameter></methodparam>
|
||||
<modifier>const</modifier><modifier>= 0</modifier>
|
||||
</methodsynopsis>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bflattenable_flattenedsize">
|
||||
<title>FlattenedSize()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<modifier>virtual</modifier><type>ssize_t</type><methodname>FlattenedSize</methodname><modifier>const</modifier><modifier>= 0</modifier>
|
||||
</methodsynopsis>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bflattenable_isfixedsize">
|
||||
<title>IsFixedSize()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<modifier>virtual</modifier><type>bool</type><methodname>IsFixedSize</methodname><modifier>const</modifier><modifier>= 0</modifier>
|
||||
</methodsynopsis>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bflattenable_typecode">
|
||||
<title>TypeCode()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<modifier>virtual</modifier><type>type_code</type><methodname>TypeCode</methodname><modifier>const</modifier><modifier>= 0</modifier>
|
||||
</methodsynopsis>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bflattenable_unflatten">
|
||||
<title>Unflatten</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<modifier>virtual</modifier><type>status_t</type><methodname>Unflatten</methodname>
|
||||
<methodparam><type>type_code</type><parameter>c</parameter></methodparam>
|
||||
<methodparam><modifier>const</modifier><type>void *</type><parameter>buf</parameter></methodparam>
|
||||
<methodparam><type>ssize_t</type><parameter>size</parameter></methodparam>
|
||||
<modifier>= 0</modifier>
|
||||
</methodsynopsis>
|
||||
</sect3>
|
||||
</sect2>
|
||||
|
||||
|
||||
@@ -1,230 +0,0 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
|
||||
<sect2 id="blist">
|
||||
<title>BList</title>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem><para><emphasis>Derived from:</emphasis> none</para></listitem>
|
||||
<listitem><para><emphasis>Declared in:</emphasis> <filename>os/support/List.h</filename></para></listitem>
|
||||
<listitem><para><emphasis>Library:</emphasis> <filename>libbe.so</filename></para></listitem>
|
||||
</itemizedlist>
|
||||
|
||||
<para>BList is a is a simple ordered list of data pointers.</para>
|
||||
|
||||
<bridgehead renderas="sect2">Constructors and Destructors</bridgehead>
|
||||
|
||||
<sect3 id="blist_constructor">
|
||||
<title>BList()</title>
|
||||
|
||||
<constructorsynopsis>
|
||||
<methodname>BList</methodname>
|
||||
<methodparam><type>int32</type><parameter>count</parameter><initializer>20</initializer></methodparam>
|
||||
</constructorsynopsis>
|
||||
|
||||
<constructorsynopsis>
|
||||
<methodname>BList</methodname>
|
||||
<methodparam><modifier>const</modifier><type>BList &</type><parameter>list</parameter></methodparam>
|
||||
</constructorsynopsis>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="blist_destructor">
|
||||
<title>~BList()</title>
|
||||
|
||||
<destructorsynopsis>
|
||||
<methodname>~BList</methodname>
|
||||
</destructorsynopsis>
|
||||
</sect3>
|
||||
|
||||
<bridgehead renderas="sect2">Member Functions</bridgehead>
|
||||
<sect3 id="blist_additem">
|
||||
<title>AddItem()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>bool</type><methodname>AddItem</methodname>
|
||||
<methodparam><type>void *</type><parameter>item</parameter></methodparam>
|
||||
<methodparam><type>int32</type><parameter>index</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>bool</type><methodname>AddItem</methodname>
|
||||
<methodparam><type>void *</type><parameter>item</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="blist_addlist">
|
||||
<title>AddList()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>bool</type><methodname>AddList</methodname>
|
||||
<methodparam><modifier>const</modifier><type>BList *</type><parameter>list</parameter></methodparam>
|
||||
<methodparam><type>int32</type><parameter>index</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>bool</type><methodname>AddList</methodname>
|
||||
<methodparam><modifier>const</modifier><type>BList *</type><parameter>list</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="blist_countitems">
|
||||
<title>CountItems()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>int32</type><methodname>CountItems</methodname><modifier>const</modifier>
|
||||
</methodsynopsis>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="blist_doforeach">
|
||||
<title>DoForEach()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<void/><methodname>DoForEach</methodname>
|
||||
<methodparam><type>bool</type><parameter>(*func)(void *)</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
|
||||
<methodsynopsis>
|
||||
<void/><methodname>DoForEach</methodname>
|
||||
<methodparam><type>bool</type><parameter>(*func)(void *, void *)</parameter></methodparam>
|
||||
<methodparam><type>void *</type><parameter>arg2</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="blist_firstitem">
|
||||
<title>FirstItem()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>void *</type><methodname>FirstItem()</methodname><modifier>const</modifier>
|
||||
</methodsynopsis>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="blist_hasitem">
|
||||
<title>HasItem()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>bool</type><methodname>HasItem</methodname>
|
||||
<methodparam><type>void *</type><parameter>item</parameter></methodparam>
|
||||
<modifier>const</modifier>
|
||||
</methodsynopsis>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="blist_indexof">
|
||||
<title>IndexOf()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>int32</type><methodname>IndexOf</methodname>
|
||||
<methodparam><type>void *</type><parameter>item</parameter></methodparam>
|
||||
<modifier>const</modifier>
|
||||
</methodsynopsis>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="blist_itemat">
|
||||
<title>ItemAt()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>void *</type><methodname>ItemAt</methodname>
|
||||
<methodparam><type>int32</type><parameter>index</parameter></methodparam>
|
||||
<modifier>const</modifier>
|
||||
</methodsynopsis>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>void *</type><methodname>ItemAtFast</methodname>
|
||||
<methodparam><type>int32</type><parameter>index</parameter></methodparam>
|
||||
<modifier>const</modifier>
|
||||
</methodsynopsis>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="blist_itematfast">
|
||||
<title>ItemAtFast()</title>
|
||||
|
||||
<para>See ItemAt()</para>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="blist_items">
|
||||
<title>Items()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>void *</type><methodname>Items</methodname><modifier>const</modifier>
|
||||
</methodsynopsis>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="blist_isempty">
|
||||
<title>IsEmpty</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>bool</type><methodname>IsEmpty</methodname><modifier>const</modifier>
|
||||
</methodsynopsis>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="blist_lastitem">
|
||||
<title>LastItem()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>void *</type><methodname>LastItem</methodname><modifier>const</modifier>
|
||||
</methodsynopsis>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="blist_moveitem">
|
||||
<title>MoveItem()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>bool</type><methodname>MoveItem</methodname>
|
||||
<methodparam><type>int32</type><parameter>fromIndex</parameter></methodparam>
|
||||
<methodparam><type>int32</type><parameter>toIndex</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="blist_removeitem">
|
||||
<title>RemoveItem()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>bool</type><methodname>RemoveItem</methodname>
|
||||
<methodparam><type>void *</type><parameter>item</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>void *</type><methodname>RemoveItem</methodname>
|
||||
<methodparam><type>int32</type><parameter>index</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>bool</type><methodname>RemoveItems</methodname>
|
||||
<methodparam><type>int32</type><parameter>index</parameter></methodparam>
|
||||
<methodparam><type>int32</type><parameter>count</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="blist_removeitems">
|
||||
<title>RemoveItems()</title>
|
||||
|
||||
<para>See RemoveItem()</para>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="blist_replaceitem">
|
||||
<title>ReplaceItem()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>bool</type><methodname>ReplaceItem</methodname>
|
||||
<methodparam><type>int32</type><parameter>index</parameter></methodparam>
|
||||
<methodparam><type>void *</type><parameter>newItem</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="blist_sortitems">
|
||||
<title>SortItems()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<void/><methodname>SortItems</methodname>
|
||||
<methodparam><type>int</type><parameter>(int (*compareFunc)(const void *, const void *)</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="blist_swapitems">
|
||||
<title>SwapItems()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>bool</type><methodname>SwapItems</methodname>
|
||||
<methodparam><type>int32</type><parameter>indexA</parameter></methodparam>
|
||||
<methodparam><type>int32</type><parameter>indexB</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
</sect3>
|
||||
</sect2>
|
||||
@@ -1,120 +0,0 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
|
||||
<sect2 id="blocker">
|
||||
<title>BLocker</title>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem><para><emphasis>Derived from:</emphasis> none</para></listitem>
|
||||
<listitem><para><emphasis>Declared in:</emphasis> <filename>os/support/Locker.h</filename></para></listitem>
|
||||
<listitem><para><emphasis>Library:</emphasis> <filename>libbe.so</filename></para></listitem>
|
||||
</itemizedlist>
|
||||
|
||||
<para><classname>BLocker</classname> implements a locking mechanism that can be used to protect multithreaded code.</para>
|
||||
|
||||
<bridgehead renderas="sect2">Constructors and Destructors</bridgehead>
|
||||
<sect3 id="blocker_constructor">
|
||||
<title>BLocker()</title>
|
||||
|
||||
<constructorsynopsis>
|
||||
<methodname>BLocker</methodname>
|
||||
</constructorsynopsis>
|
||||
|
||||
<constructorsynopsis>
|
||||
<methodname>BLocker</methodname>
|
||||
<methodparam><modifier>const</modifier><type>char *</type><parameter>name</parameter></methodparam>
|
||||
</constructorsynopsis>
|
||||
|
||||
<constructorsynopsis>
|
||||
<methodname>BLocker</methodname>
|
||||
<methodparam><type>bool</type><parameter>benaphore_style</parameter></methodparam>
|
||||
</constructorsynopsis>
|
||||
|
||||
<constructorsynopsis>
|
||||
<methodname>BLocker</methodname>
|
||||
<methodparam><modifier>const</modifier><type>char *</type><parameter>name</parameter></methodparam>
|
||||
<methodparam><type>bool</type><parameter>benaphore_style</parameter></methodparam>
|
||||
</constructorsynopsis>
|
||||
|
||||
<constructorsynopsis>
|
||||
<methodname>BLocker</methodname>
|
||||
<methodparam><modifier>const</modifier><type>char *</type><parameter>name</parameter></methodparam>
|
||||
<methodparam><type>bool</type><parameter>benaphore_style</parameter></methodparam>
|
||||
<methodparam><type>bool</type><parameter>bogus</parameter></methodparam>
|
||||
</constructorsynopsis>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="blocker_destructor">
|
||||
<title>~BLocker()</title>
|
||||
|
||||
<destructorsynopsis>
|
||||
<modifier>virtual</modifier><methodname>~BLocker</methodname>
|
||||
</destructorsynopsis>
|
||||
</sect3>
|
||||
|
||||
<bridgehead renderas="sect2">Member Functions</bridgehead>
|
||||
<sect3 id="blocker_countlocks">
|
||||
<title>CountLocks()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>int32</type><methodname>CountLocks</methodname><modifier>const</modifier>
|
||||
</methodsynopsis>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="blocker_countlockrequest">
|
||||
<title>CountLockRequests()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>int32</type><methodname>CountLockRequests</methodname><modifier>const</modifier>
|
||||
</methodsynopsis>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="blocker_islocked">
|
||||
<title>IsLocked()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>bool</type><methodname>IsLocked</methodname><modifier>const</modifier>
|
||||
</methodsynopsis>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="blocker_lock">
|
||||
<title>Lock()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>bool</type><methodname>Lock</methodname>
|
||||
</methodsynopsis>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="blocker_lockingthread">
|
||||
<title>LockingThread()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>thread_id</type><methodname>LockingThread</methodname><modifier>const</modifier>
|
||||
</methodsynopsis>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="blocker_lockwithtimeout">
|
||||
<title>LockWithTimeout()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>status_t</type><methodname>LockWithTimeout</methodname>
|
||||
<methodparam><type>bigtime_t</type><parameter>timeout</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="blocker_sem">
|
||||
<title>Sem()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>sem_id</type><methodname>Sem</methodname><modifier>const</modifier>
|
||||
</methodsynopsis>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="blocker_unlock">
|
||||
<title>Unlock()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<void/><methodname>Unlock</methodname>
|
||||
</methodsynopsis>
|
||||
</sect3>
|
||||
|
||||
</sect2>
|
||||
@@ -1,105 +0,0 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
|
||||
<sect2 id="bmallocio">
|
||||
<title>BMallocIO</title>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem><para><emphasis>Derived from:</emphasis><link linkend="bpositionio"><classname>BPositionIO</classname></link></para></listitem>
|
||||
<listitem><para><emphasis>Declared in:</emphasis> <filename>os/support/DataIO.h</filename></para></listitem>
|
||||
<listitem><para><emphasis>Library:</emphasis> <filename>libbe.so</filename></para></listitem>
|
||||
</itemizedlist>
|
||||
|
||||
<para><classname>BMallocIO</classname> provides an interface for reading, writing and seeking in a buffer that it maintains itself.</para>
|
||||
|
||||
<bridgehead renderas="sect2">Constructors and Destructors</bridgehead>
|
||||
<sect3 id="bmallocio_constructor">
|
||||
<title>BMallocIO()</title>
|
||||
|
||||
<constructorsynopsis>
|
||||
<methodname>BMallocIO</methodname>
|
||||
</constructorsynopsis>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bmallocio_destructor">
|
||||
<title>~BMallocIO()</title>
|
||||
|
||||
<destructorsynopsis>
|
||||
<modifier>virtual</modifier><methodname>~BMallocIO</methodname>
|
||||
</destructorsynopsis>
|
||||
</sect3>
|
||||
|
||||
<bridgehead renderas="sect2">Member functions</bridgehead>
|
||||
<sect3 id="bmallocio_buffer">
|
||||
<title>Buffer()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>const void *</type><methodname>Buffer</methodname><modifier>const</modifier>
|
||||
</methodsynopsis>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bmallocio_bufferlength">
|
||||
<title>BufferLength()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>size_t</type><methodname>BufferLength()</methodname><modifier>const</modifier>
|
||||
</methodsynopsis>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bmallocio_position">
|
||||
<title>Position()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<modifier>virtual</modifier><type>off_t</type><methodname>Position</methodname><modifier>const</modifier>
|
||||
</methodsynopsis>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bmallocio_readat">
|
||||
<title>ReadAt()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<modifier>virtual</modifier><type>ssize_t</type><methodname>ReadAt</methodname>
|
||||
<methodparam><type>off_t</type><parameter>position</parameter></methodparam>
|
||||
<methodparam><type>void *</type><parameter>buffer</parameter></methodparam>
|
||||
<methodparam><type>size_t</type><parameter>size</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bmallocio_seek">
|
||||
<title>Seek()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<modifier>virtual</modifier><type>off_t</type><methodname>Seek</methodname>
|
||||
<methodparam><type>off_t</type><parameter>position</parameter></methodparam>
|
||||
<methodparam><type>uint32</type><parameter>seekMode</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bmallocio_setblocksize">
|
||||
<title>SetBlockSize()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<void/><methodname>SetBlockSize</methodname>
|
||||
<methodparam><type>size_t</type><parameter>blockSize</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bmallocio_setsize">
|
||||
<title>SetSize()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<modifier>virtual</modifier><type>status_t</type><methodname>SetSize</methodname>
|
||||
<methodparam><type>off_t</type><parameter>size</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bmallocio_writeat">
|
||||
<title>WriteAt()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<modifier>virtual</modifier><type>ssize_t</type><methodname>WriteAt</methodname>
|
||||
<methodparam><type>off_t</type><parameter>position</parameter></methodparam>
|
||||
<methodparam><modifier>const</modifier><type>void *</type><parameter>buffer</parameter></methodparam>
|
||||
<methodparam><type>size_t</type><parameter>size</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
</sect3>
|
||||
</sect2>
|
||||
@@ -1,88 +0,0 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
|
||||
<sect2 id="bmemoryio">
|
||||
<title>BMemoryIO</title>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem><para><emphasis>Derived from:</emphasis><link linkend="bpositionio"><classname>BPositionIO</classname></link></para></listitem>
|
||||
<listitem><para><emphasis>Declared in:</emphasis> <filename>os/support/DataIO.h</filename></para></listitem>
|
||||
<listitem><para><emphasis>Library:</emphasis> <filename>libbe.so</filename></para></listitem>
|
||||
</itemizedlist>
|
||||
|
||||
<para><classname>BMemoryIO</classname> implements reading, writing and seeking in a data buffer.</para>
|
||||
|
||||
<bridgehead renderas="sect2">Constructors and Destructors</bridgehead>
|
||||
<sect3 id="bmemoryio_constructor">
|
||||
<title>BMemoryIO()</title>
|
||||
|
||||
<constructorsynopsis>
|
||||
<methodname>BMemoryIO</methodname>
|
||||
<methodparam><type>void *</type><parameter>data</parameter></methodparam>
|
||||
<methodparam><type>size_t</type><parameter>length</parameter></methodparam>
|
||||
</constructorsynopsis>
|
||||
|
||||
<constructorsynopsis>
|
||||
<methodname>BMemoryIO</methodname>
|
||||
<methodparam><modifier>const</modifier><type>void *</type><parameter>data</parameter></methodparam>
|
||||
<methodparam><type>size_t</type><parameter>length</parameter></methodparam>
|
||||
</constructorsynopsis>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bmemoryio_destructor">
|
||||
<title>~BMemoryIO()</title>
|
||||
|
||||
<destructorsynopsis>
|
||||
<modifier>virtual</modifier><methodname>~BMemoryIO</methodname>
|
||||
</destructorsynopsis>
|
||||
</sect3>
|
||||
|
||||
<bridgehead renderas="sect2">Member functions</bridgehead>
|
||||
<sect3 id="bmemoryio_position">
|
||||
<title>Position()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<modifier>virtual</modifier><type>off_t</type><methodname>Position</methodname><modifier>const</modifier>
|
||||
</methodsynopsis>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bmemoryio_readat">
|
||||
<title>ReadAt()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<modifier>virtual</modifier><type>ssize_t</type><methodname>ReadAt</methodname>
|
||||
<methodparam><type>off_t</type><parameter>position</parameter></methodparam>
|
||||
<methodparam><type>void *</type><parameter>buffer</parameter></methodparam>
|
||||
<methodparam><type>size_t</type><parameter>size</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bmemoryio_seek">
|
||||
<title>Seek()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<modifier>virtual</modifier><type>off_t</type><methodname>Seek</methodname>
|
||||
<methodparam><type>off_t</type><parameter>position</parameter></methodparam>
|
||||
<methodparam><type>uint32</type><parameter>seekMode</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bmemoryio_setsize">
|
||||
<title>SetSize()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<modifier>virtual</modifier><type>status_t</type><methodname>SetSize</methodname>
|
||||
<methodparam><type>off_t</type><parameter>size</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bmemoryio_writeat">
|
||||
<title>WriteAt()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<modifier>virtual</modifier><type>ssize_t</type><methodname>WriteAt</methodname>
|
||||
<methodparam><type>off_t</type><parameter>position</parameter></methodparam>
|
||||
<methodparam><modifier>const</modifier><type>void *</type><parameter>buffer</parameter></methodparam>
|
||||
<methodparam><type>size_t</type><parameter>size</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
</sect3>
|
||||
</sect2>
|
||||
@@ -1,112 +0,0 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
|
||||
<sect2 id="bpositionio">
|
||||
<title>BPositionIO</title>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem><para><emphasis>Derived from:</emphasis><link linkend="bdataio"><classname>BDataIO</classname></link></para></listitem>
|
||||
<listitem><para><emphasis>Declared in:</emphasis> <filename>os/support/DataIO.h</filename></para></listitem>
|
||||
<listitem><para><emphasis>Library:</emphasis> <filename>libbe.so</filename></para></listitem>
|
||||
</itemizedlist>
|
||||
|
||||
<para><classname>BPositionIO</classname> provides an interface for reading, writing and seeking within data.</para>
|
||||
|
||||
<bridgehead renderas="sect2">Constructors and Destructors</bridgehead>
|
||||
<sect3 id="bpositionio_constructor">
|
||||
<title>BPositionIO()</title>
|
||||
|
||||
<constructorsynopsis>
|
||||
<methodname>BPositionIO</methodname>
|
||||
</constructorsynopsis>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bpositionio_destructor">
|
||||
<title>~BPositionIO()</title>
|
||||
|
||||
<destructorsynopsis>
|
||||
<modifier>virtual</modifier><methodname>~BPositionIO</methodname>
|
||||
</destructorsynopsis>
|
||||
</sect3>
|
||||
|
||||
<bridgehead renderas="sect2">Member functions</bridgehead>
|
||||
<sect3 id="bpositionio_getsize">
|
||||
<title>GetSize()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<modifier>virtual</modifier><type>status_t</type><methodname>GetSize</methodname>
|
||||
<methodparam><type>off_t *</type><parameter>size</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bpositionio_position">
|
||||
<title>Position()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<modifier>virtual</modifier><type>off_t</type><methodname>Position</methodname><modifier>const</modifier><modifier>= 0</modifier>
|
||||
</methodsynopsis>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bpositionio_read">
|
||||
<title>Read()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<modifier>virtual</modifier><type>ssize_t</type><methodname>Read</methodname>
|
||||
<methodparam><type>void *</type><parameter>buffer</parameter></methodparam>
|
||||
<methodparam><type>size_t</type><parameter>size</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bpositionio_readat">
|
||||
<title>ReadAt()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<modifier>virtual</modifier><type>ssize_t</type><methodname>ReadAt</methodname>
|
||||
<methodparam><type>off_t</type><parameter>position</parameter></methodparam>
|
||||
<methodparam><type>void *</type><parameter>buffer</parameter></methodparam>
|
||||
<methodparam><type>size_t</type><parameter>size</parameter></methodparam>
|
||||
<modifier>= 0</modifier>
|
||||
</methodsynopsis>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bpositionio_seek">
|
||||
<title>Seek()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<modifier>virtual</modifier><type>off_t</type><methodname>Seek</methodname>
|
||||
<methodparam><type>off_t</type><parameter>position</parameter></methodparam>
|
||||
<methodparam><type>uint32</type><parameter>seekMode</parameter></methodparam>
|
||||
<modifier>= 0</modifier>
|
||||
</methodsynopsis>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bpositionio_setsize">
|
||||
<title>SetSize()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<modifier>virtual</modifier><type>status_t</type><methodname>SetSize</methodname>
|
||||
<methodparam><type>off_t</type><parameter>size</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bpositionio_write">
|
||||
<title>Write()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<modifier>virtual</modifier><type>ssize_t</type><methodname>Write</methodname>
|
||||
<methodparam><modifier>const</modifier><type>void *</type><parameter>buffer</parameter></methodparam>
|
||||
<methodparam><type>size_t</type><parameter>size</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bpositionio_writeat">
|
||||
<title>WriteAt()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<modifier>virtual</modifier><type>ssize_t</type><methodname>WriteAt</methodname>
|
||||
<methodparam><type>off_t</type><parameter>position</parameter></methodparam>
|
||||
<methodparam><modifier>const</modifier><type>void *</type><parameter>buffer</parameter></methodparam>
|
||||
<methodparam><type>size_t</type><parameter>size</parameter></methodparam>
|
||||
<modifier>= 0</modifier>
|
||||
</methodsynopsis>
|
||||
</sect3>
|
||||
</sect2>
|
||||
@@ -1,151 +0,0 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
|
||||
<sect2 id="bstopwatch">
|
||||
<title>BStopWatch</title>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem><para><emphasis>Derived from:</emphasis> none</para></listitem>
|
||||
<listitem><para><emphasis>Declared in:</emphasis> <filename>os/support/StopWatch.h</filename></para></listitem>
|
||||
<listitem><para><emphasis>Library:</emphasis> <filename>libbe.so</filename></para></listitem>
|
||||
</itemizedlist>
|
||||
|
||||
<para><classname>BStopWatch</classname> is a timer class.</para>
|
||||
|
||||
<para>
|
||||
This class provides method to time events. The interface is designed to behave like a
|
||||
physical stopwatch. It is especially useful for debugging certain parts of your code, since
|
||||
it can behave like a 'cheap' profiler.
|
||||
</para>
|
||||
|
||||
<bridgehead renderas="sect2">Constructors and Destructors</bridgehead>
|
||||
<sect3 id="bstopwatch_constructor">
|
||||
<title>BStopWatch()</title>
|
||||
|
||||
<constructorsynopsis>
|
||||
<methodname>BStopWatch</methodname>
|
||||
<methodparam><modifier>const</modifier><type>char *</type><parameter>name</parameter></methodparam>
|
||||
<methodparam><type>bool</type><parameter>silent</parameter><initializer>false</initializer></methodparam>
|
||||
</constructorsynopsis>
|
||||
|
||||
<para>
|
||||
The constructor creates a clean <classname>BStopWatch</classname> object. This object
|
||||
can be given a <parameter>name</parameter>. As soon as the object is created, the time
|
||||
will start ticking away. This class is designed to be usuable as a primitive profiling tool.
|
||||
If you are profiling your code with this class, pass <literal>true</literal> as the
|
||||
<parameter>silent</parameter> parameter. Whenever the object is destroyed, information on
|
||||
the elapsed time will be streamed to standard output.
|
||||
</para>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bstopwatch_destructor">
|
||||
<title>~BStopWatch()</title>
|
||||
|
||||
<destructorsynopsis>
|
||||
<modifier>virtual</modifier><methodname>~BStopWatch</methodname>
|
||||
</destructorsynopsis>
|
||||
|
||||
<para>
|
||||
Destroys the object. If the object was constructed with the parameter
|
||||
<literal>silent</literal> set t to <literal>false</literal>, this destructor will print
|
||||
information on the elapsed time to standard output.
|
||||
</para>
|
||||
</sect3>
|
||||
|
||||
<bridgehead renderas="sect2">Member Functions</bridgehead>
|
||||
<sect3 id="bstopwatch_elapsedtime">
|
||||
<title>ElapsedTime()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>bigtime_t</type><methodname>ElapsedTime</methodname><modifier>const</modifier>
|
||||
</methodsynopsis>
|
||||
|
||||
<para>
|
||||
This method returns the elapsed time in microseconds since the object was created. If
|
||||
the object is suspended, the time until the suspend will be returned.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
See also: Suspend().
|
||||
</para>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bstopwatch_lap">
|
||||
<title>Lap</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>bigtime_t</type><methodname>Lap</methodname>
|
||||
</methodsynopsis>
|
||||
|
||||
<para>
|
||||
This method sets a lap. With the current implementation you are unable to actually
|
||||
retrieve the timings of the laps. This is only printed to the standard output when the
|
||||
object is destroyed. Thus making this tool only usuable for use when doing some
|
||||
profiling.
|
||||
</para>
|
||||
|
||||
<note><para>
|
||||
Please note that the current implementation is limited to 10 laps. The value returned
|
||||
is the time that has passed since the timer was started (and not the time that has
|
||||
passed since the last lap). Any lap call beyond the 10th lap will overwrite the last
|
||||
value. Note that if the timer is suspended, nothing happens and the method will return
|
||||
<returnvalue>0</returnvalue>.
|
||||
</para></note>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bstopwatch_name">
|
||||
<title>Name()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>const char *</type><methodname>Name</methodname><modifier>const</modifier>
|
||||
</methodsynopsis>
|
||||
|
||||
<para>
|
||||
Returns the name that was given when the object was constructed.
|
||||
</para>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bstopwatch_reset">
|
||||
<title>Reset()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<void/><methodname>Reset</methodname>
|
||||
</methodsynopsis>
|
||||
|
||||
<para>
|
||||
Resets the object: it clears the start time, it clears the stored laps and it restarts
|
||||
the timer.
|
||||
</para>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bstopwatch_resume">
|
||||
<title>Resume()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<void/><methodname>Resume</methodname>
|
||||
</methodsynopsis>
|
||||
|
||||
<para>
|
||||
Resumes the timer when it is in a suspended state.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
See Also: Suspend().
|
||||
</para>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bstopwatch_suspend">
|
||||
<title>Suspend()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<void/><methodname>Suspend</methodname>
|
||||
</methodsynopsis>
|
||||
|
||||
<para>
|
||||
Suspends the timer.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
See Also: Resume().
|
||||
</para>
|
||||
</sect3>
|
||||
</sect2>
|
||||
@@ -1,663 +0,0 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
|
||||
<sect2 id="bstring">
|
||||
<title>BString</title>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem><para><emphasis>Derived from:</emphasis> none</para></listitem>
|
||||
<listitem><para><emphasis>Declared in:</emphasis> <filename>os/support/String.h</filename></para></listitem>
|
||||
<listitem><para><emphasis>Library:</emphasis> <filename>libbe.so</filename></para></listitem>
|
||||
</itemizedlist>
|
||||
|
||||
<para><classname>BString</classname> implements a high level string object.</para>
|
||||
|
||||
<bridgehead renderas="sect2">Constructors and Destructors</bridgehead>
|
||||
<sect3 id="bstring_constructor">
|
||||
<title>BString()</title>
|
||||
|
||||
<constructorsynopsis>
|
||||
<methodname>BString</methodname>
|
||||
</constructorsynopsis>
|
||||
|
||||
<constructorsynopsis>
|
||||
<methodname>BString</methodname>
|
||||
<methodparam><modifier>const</modifier><type>char *</type><parameter>string</parameter></methodparam>
|
||||
</constructorsynopsis>
|
||||
|
||||
<constructorsynopsis>
|
||||
<methodname>BString</methodname>
|
||||
<methodparam><modifier>const</modifier><type>BString &</type><parameter>string</parameter></methodparam>
|
||||
</constructorsynopsis>
|
||||
|
||||
<constructorsynopsis>
|
||||
<methodname>BString</methodname>
|
||||
<methodparam><modifier>const</modifier><type>char *</type><parameter>string</parameter></methodparam>
|
||||
<methodparam><type>int32</type><parameter>maxLength</parameter></methodparam>
|
||||
</constructorsynopsis>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bstring_destructor">
|
||||
<title>~BString()</title>
|
||||
|
||||
<destructorsynopsis>
|
||||
<methodname>~BString()</methodname>
|
||||
</destructorsynopsis>
|
||||
</sect3>
|
||||
|
||||
<bridgehead renderas="sect2">Member Functions</bridgehead>
|
||||
<sect3 id="bstring_adopt">
|
||||
<title>Adopt()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>BString &</type><methodname>Adopt</methodname>
|
||||
<methodparam><type>BString &</type><parameter>from</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>BString &</type><methodname>Adopt</methodname>
|
||||
<methodparam><type>BString &</type><parameter>from</parameter></methodparam>
|
||||
<methodparam><type>int32</type><parameter>length</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bstring_append">
|
||||
<title>Append()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>BString &</type><methodname>Append</methodname>
|
||||
<methodparam><modifier>const</modifier><type>BString &</type><parameter>string</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>BString &</type><methodname>Append</methodname>
|
||||
<methodparam><modifier>const</modifier><type> char *</type><parameter>string</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>BString &</type><methodname>Append</methodname>
|
||||
<methodparam><modifier>const</modifier><type>BString &</type><parameter>string</parameter></methodparam>
|
||||
<methodparam><type>int32</type><parameter>length</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>BString &</type><methodname>Append</methodname>
|
||||
<methodparam><modifier>const</modifier><type>char *</type><parameter>string</parameter></methodparam>
|
||||
<methodparam><type>int32</type><parameter>length</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>BString &</type><methodname>Append</methodname>
|
||||
<methodparam><type>char</type><parameter>string</parameter></methodparam>
|
||||
<methodparam><type>int32</type><parameter>count</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bstring_compare">
|
||||
<title>Compare()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>int</type><methodname>Compare</methodname>
|
||||
<methodparam><modifier>const</modifier><type>BString &</type><parameter>string</parameter></methodparam>
|
||||
<modifier>const</modifier>
|
||||
</methodsynopsis>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>int</type><methodname>Compare</methodname>
|
||||
<methodparam><modifier>const</modifier><type>char *</type><parameter>string</parameter></methodparam>
|
||||
<modifier>const</modifier>
|
||||
</methodsynopsis>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>int</type><methodname>Compare</methodname>
|
||||
<methodparam><modifier>const</modifier><type>BString &</type><parameter>string</parameter></methodparam>
|
||||
<methodparam><type>int32</type><parameter>n</parameter></methodparam>
|
||||
<modifier>const</modifier>
|
||||
</methodsynopsis>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>int</type><methodname>Compare</methodname>
|
||||
<methodparam><modifier>const</modifier><type>char *</type><parameter>string</parameter></methodparam>
|
||||
<methodparam><type>int32</type><parameter>n</parameter></methodparam>
|
||||
<modifier>const</modifier>
|
||||
</methodsynopsis>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bstring_copyinto">
|
||||
<title>CopyInto()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>BString &</type><methodname>CopyInto</methodname>
|
||||
<methodparam><type>BString &</type><parameter>into</parameter></methodparam>
|
||||
<methodparam><type>int32</type><parameter>fromOffset</parameter></methodparam>
|
||||
<methodparam><type>int32</type><parameter>length</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
|
||||
<methodsynopsis>
|
||||
<void/><methodname>CopyInto</methodname>
|
||||
<methodparam><type>char *</type><parameter>into</parameter></methodparam>
|
||||
<methodparam><type>int32</type><parameter>fromOffset</parameter></methodparam>
|
||||
<methodparam><type>int32</type><parameter>length</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bstring_countchars">
|
||||
<title>CountChars()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>int32</type><methodname>CountChars</methodname><modifier>const</modifier>
|
||||
</methodsynopsis>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bstring_findfirst">
|
||||
<title>FindFirst()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>int32</type><methodname>FindFirst</methodname>
|
||||
<methodparam><modifier>const</modifier><type>BString &</type><parameter>string</parameter></methodparam>
|
||||
<modifier>const</modifier>
|
||||
</methodsynopsis>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>int32</type><methodname>FindFirst</methodname>
|
||||
<methodparam><modifier>const</modifier><type>char *</type><parameter>string</parameter></methodparam>
|
||||
<modifier>const</modifier>
|
||||
</methodsynopsis>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>int32</type><methodname>FindFirst</methodname>
|
||||
<methodparam><modifier>const</modifier><type>BString &</type><parameter>string</parameter></methodparam>
|
||||
<methodparam><type>int32</type><parameter>fromOffset</parameter></methodparam>
|
||||
<modifier>const</modifier>
|
||||
</methodsynopsis>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>int32</type><methodname>FindFirst</methodname>
|
||||
<methodparam><modifier>const</modifier><type>char *</type><parameter>string</parameter></methodparam>
|
||||
<methodparam><type>int32</type><parameter>fromOffset</parameter></methodparam>
|
||||
<modifier>const</modifier>
|
||||
</methodsynopsis>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>int32</type><methodname>FindFirst</methodname>
|
||||
<methodparam><type>char</type><parameter>character</parameter></methodparam>
|
||||
<modifier>const</modifier>
|
||||
</methodsynopsis>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>int32</type><methodname>FindFirst</methodname>
|
||||
<methodparam><type>char</type><parameter>character</parameter></methodparam>
|
||||
<methodparam><type>int32</type><parameter>fromOffset</parameter></methodparam>
|
||||
<modifier>const</modifier>
|
||||
</methodsynopsis>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bstring_findlast">
|
||||
<title>FindLast()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>int32</type><methodname>FindLast</methodname>
|
||||
<methodparam><modifier>const</modifier><type>BString &</type><parameter>string</parameter></methodparam>
|
||||
<modifier>const</modifier>
|
||||
</methodsynopsis>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>int32</type><methodname>FindLast</methodname>
|
||||
<methodparam><modifier>const</modifier><type>char *</type><parameter>string</parameter></methodparam>
|
||||
<modifier>const</modifier>
|
||||
</methodsynopsis>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>int32</type><methodname>FindLast</methodname>
|
||||
<methodparam><modifier>const</modifier><type>BString &</type><parameter>string</parameter></methodparam>
|
||||
<methodparam><type>int32</type><parameter>beforeOffset</parameter></methodparam>
|
||||
<modifier>const</modifier>
|
||||
</methodsynopsis>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>int32</type><methodname>FindLast</methodname>
|
||||
<methodparam><modifier>const</modifier><type>char *</type><parameter>string</parameter></methodparam>
|
||||
<methodparam><type>int32</type><parameter>beforeOffset</parameter></methodparam>
|
||||
<modifier>const</modifier>
|
||||
</methodsynopsis>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>int32</type><methodname>FindLast</methodname>
|
||||
<methodparam><type>char</type><parameter>character</parameter></methodparam>
|
||||
<modifier>const</modifier>
|
||||
</methodsynopsis>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>int32</type><methodname>FindLast</methodname>
|
||||
<methodparam><type>char</type><parameter>character</parameter></methodparam>
|
||||
<methodparam><type>int32</type><parameter>beforeOffset</parameter></methodparam>
|
||||
<modifier>const</modifier>
|
||||
</methodsynopsis>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bstring_icompare">
|
||||
<title>ICompare()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>int</type><methodname>ICompare</methodname>
|
||||
<methodparam><modifier>const</modifier><type>BString &</type><parameter>string</parameter></methodparam>
|
||||
<modifier>const</modifier>
|
||||
</methodsynopsis>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>int</type><methodname>ICompare</methodname>
|
||||
<methodparam><modifier>const</modifier><type>char *</type><parameter>string</parameter></methodparam>
|
||||
<modifier>const</modifier>
|
||||
</methodsynopsis>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>int</type><methodname>ICompare</methodname>
|
||||
<methodparam><modifier>const</modifier><type>BString &</type><parameter>string</parameter></methodparam>
|
||||
<methodparam><type>int32</type><parameter>n</parameter></methodparam>
|
||||
<modifier>const</modifier>
|
||||
</methodsynopsis>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>int</type><methodname>ICompare</methodname>
|
||||
<methodparam><modifier>const</modifier><type>char *</type><parameter>string</parameter></methodparam>
|
||||
<methodparam><type>int32</type><parameter>n</parameter></methodparam>
|
||||
<modifier>const</modifier>
|
||||
</methodsynopsis>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bstring_ifindfirst">
|
||||
<title>IFindFirst()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>int32</type><methodname>IFindFirst</methodname>
|
||||
<methodparam><modifier>const</modifier><type>BString &</type><parameter>string</parameter></methodparam>
|
||||
<modifier>const</modifier>
|
||||
</methodsynopsis>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>int32</type><methodname>IFindFirst</methodname>
|
||||
<methodparam><modifier>const</modifier><type>char *</type><parameter>string</parameter></methodparam>
|
||||
<modifier>const</modifier>
|
||||
</methodsynopsis>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>int32</type><methodname>IFindFirst</methodname>
|
||||
<methodparam><modifier>const</modifier><type>BString &</type><parameter>string</parameter></methodparam>
|
||||
<methodparam><type>int32</type><parameter>fromOffset</parameter></methodparam>
|
||||
<modifier>const</modifier>
|
||||
</methodsynopsis>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>int32</type><methodname>IFindFirst</methodname>
|
||||
<methodparam><modifier>const</modifier><type>char *</type><parameter>string</parameter></methodparam>
|
||||
<methodparam><type>int32</type><parameter>fromOffset</parameter></methodparam>
|
||||
<modifier>const</modifier>
|
||||
</methodsynopsis>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bstring_ifindlast">
|
||||
<title>IFindLast()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>int32</type><methodname>IFindLast</methodname>
|
||||
<methodparam><modifier>const</modifier><type>BString &</type><parameter>string</parameter></methodparam>
|
||||
<modifier>const</modifier>
|
||||
</methodsynopsis>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>int32</type><methodname>IFindLast</methodname>
|
||||
<methodparam><modifier>const</modifier><type>char *</type><parameter>string</parameter></methodparam>
|
||||
<modifier>const</modifier>
|
||||
</methodsynopsis>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>int32</type><methodname>IFindLast</methodname>
|
||||
<methodparam><modifier>const</modifier><type>BString &</type><parameter>string</parameter></methodparam>
|
||||
<methodparam><type>int32</type><parameter>beforeOffset</parameter></methodparam>
|
||||
<modifier>const</modifier>
|
||||
</methodsynopsis>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>int32</type><methodname>IFindLast</methodname>
|
||||
<methodparam><modifier>const</modifier><type>char *</type><parameter>string</parameter></methodparam>
|
||||
<methodparam><type>int32</type><parameter>beforeOffset</parameter></methodparam>
|
||||
<modifier>const</modifier>
|
||||
</methodsynopsis>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bstring_insert">
|
||||
<title>Insert()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>BString &</type><methodname>Insert</methodname>
|
||||
<methodparam><modifier>const</modifier><type>char *</type><parameter>string</parameter></methodparam>
|
||||
<methodparam><type>int32</type><parameter>pos</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>BString &</type><methodname>Insert</methodname>
|
||||
<methodparam><modifier>const</modifier><type>char *</type><parameter>string</parameter></methodparam>
|
||||
<methodparam><type>int32</type><parameter>length</parameter></methodparam>
|
||||
<methodparam><type>int32</type><parameter>pos</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>BString &</type><methodname>Insert</methodname>
|
||||
<methodparam><modifier>const</modifier><type>char *</type><parameter>string</parameter></methodparam>
|
||||
<methodparam><type>int32</type><parameter>fromOffset</parameter></methodparam>
|
||||
<methodparam><type>int32</type><parameter>length</parameter></methodparam>
|
||||
<methodparam><type>int32</type><parameter>pos</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>BString &</type><methodname>Insert</methodname>
|
||||
<methodparam><modifier>const</modifier><type>BString &</type><parameter>string</parameter></methodparam>
|
||||
<methodparam><type>int32</type><parameter>pos</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>BString &</type><methodname>Insert</methodname>
|
||||
<methodparam><modifier>const</modifier><type>BString &</type><parameter>string</parameter></methodparam>
|
||||
<methodparam><type>int32</type><parameter>length</parameter></methodparam>
|
||||
<methodparam><type>int32</type><parameter>pos</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>BString &</type><methodname>Insert</methodname>
|
||||
<methodparam><modifier>const</modifier><type>BString &</type><parameter>string</parameter></methodparam>
|
||||
<methodparam><type>int32</type><parameter>fromOffSet</parameter></methodparam>
|
||||
<methodparam><type>int32</type><parameter>length</parameter></methodparam>
|
||||
<methodparam><type>int32</type><parameter>pos</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>BString &</type><methodname>Inser</methodname>
|
||||
<methodparam><type>char</type><parameter>string</parameter></methodparam>
|
||||
<methodparam><type>int32</type><parameter>count</parameter></methodparam>
|
||||
<methodparam><type>int32</type><parameter>pos</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bstring_length">
|
||||
<title>Length()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>int32</type><methodname>Length</methodname><modifier>const</modifier>
|
||||
</methodsynopsis>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bstring_moveinto">
|
||||
<title>MoveInto()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>BString &</type><methodname>MoveInto</methodname>
|
||||
<methodparam><type>BString &</type><parameter>into</parameter></methodparam>
|
||||
<methodparam><type>int32</type><parameter>from</parameter></methodparam>
|
||||
<methodparam><type>int32</type><parameter>length</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
|
||||
<methodsynopsis>
|
||||
<void/><methodname>MoveInto</methodname>
|
||||
<methodparam><type>char *</type><parameter>into</parameter></methodparam>
|
||||
<methodparam><type>int32</type><parameter>from</parameter></methodparam>
|
||||
<methodparam><type>int32</type><parameter>length</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bstring_prepend">
|
||||
<title>Prepend()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>BString &</type><methodname>Prepend</methodname>
|
||||
<methodparam><modifier>const</modifier><type>BString &</type><parameter>string</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>BString &</type><methodname>Prepend</methodname>
|
||||
<methodparam><modifier>const</modifier><type>char *</type><parameter>string</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>BString &</type><methodname>Prepend</methodname>
|
||||
<methodparam><modifier>const</modifier><type>BString &</type><parameter>string</parameter></methodparam>
|
||||
<methodparam><type>int32</type><parameter>length</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>BString &</type><methodname>Prepend</methodname>
|
||||
<methodparam><modifier>const</modifier><type>char *</type><parameter>string</parameter></methodparam>
|
||||
<methodparam><type>int32</type><parameter>length</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>BString &</type><methodname>Prepend</methodname>
|
||||
<methodparam><type>char</type><parameter>string</parameter></methodparam>
|
||||
<methodparam><type>int32</type><parameter>count</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bstring_remove">
|
||||
<title>Remove()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>BString &</type><methodname>Remove</methodname>
|
||||
<methodparam><type>int32</type><parameter>from</parameter></methodparam>
|
||||
<methodparam><type>int32</type><parameter>length</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bstring_removefirst">
|
||||
<title>RemoveFirst()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>BString &</type><methodname>RemoveFirst</methodname>
|
||||
<methodparam><modifier>const</modifier><type>BString &</type><parameter>string</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>BString &</type><methodname>RemoveFirst</methodname>
|
||||
<methodparam><modifier>const</modifier><type>char *</type><parameter>string</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bstring_removelast">
|
||||
<title>RemoveLast()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>BString &</type><methodname>RemoveLast</methodname>
|
||||
<methodparam><modifier>const</modifier><type>BString &</type><parameter>string</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>BString &</type><methodname>RemoveLast</methodname>
|
||||
<methodparam><modifier>const</modifier><type>char *</type><parameter>string</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bstring_removeall">
|
||||
<title>RemoveAll</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>BString &</type><methodname>RemoveAll</methodname>
|
||||
<methodparam><modifier>const</modifier><type>BString &</type><parameter>string</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>BString &</type><methodname>RemoveAll</methodname>
|
||||
<methodparam><modifier>const</modifier><type>char *</type><parameter>string</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bstring_removeset">
|
||||
<title>RemoveSet</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>BString &</type><methodname>RemoveSet</methodname>
|
||||
<methodparam><modifier>const</modifier><type>char *</type><parameter>setOfCharsToRemove</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bstring_setto">
|
||||
<title>SetTo</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>BString &</type><methodname>SetTo</methodname>
|
||||
<methodparam><modifier>const</modifier><type>char *</type><parameter>string</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>BString &</type><methodname>SetTo</methodname>
|
||||
<methodparam><modifier>const</modifier><type>char *</type><parameter>string</parameter></methodparam>
|
||||
<methodparam><type>int32</type><parameter>length</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>BString &</type><methodname>SetTo</methodname>
|
||||
<methodparam><modifier>const</modifier><type>BString &</type><parameter>from</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>BString &</type><methodname>SetTo</methodname>
|
||||
<methodparam><modifier>const</modifier><type>BString &</type><parameter>from</parameter></methodparam>
|
||||
<methodparam><type>int32</type><parameter>length</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>BString &</type><methodname>SetTo</methodname>
|
||||
<methodparam><type>char</type><parameter>string</parameter></methodparam>
|
||||
<methodparam><type>int32</type><parameter>count</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bstring_string">
|
||||
<title>String()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>const char *</type><methodname>String</methodname> <modifier>const</modifier>
|
||||
</methodsynopsis>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bstring_truncate">
|
||||
<title>Truncate()</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>BString &</type><methodname>Truncate</methodname>
|
||||
<methodparam><type>int32</type><parameter>newLength</parameter></methodparam>
|
||||
<methodparam><type>bool</type><parameter>lazy</parameter><initializer>true</initializer></methodparam>
|
||||
</methodsynopsis>
|
||||
</sect3>
|
||||
|
||||
<bridgehead renderas="sect2">Operators</bridgehead>
|
||||
<sect3 id="bstring_operator_assignment">
|
||||
<title>= (assignment)</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>BString &</type><methodname>operator=</methodname>
|
||||
<methodparam><modifier>const</modifier><type>BString &</type><parameter>string</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>BString &</type><methodname>operator=</methodname>
|
||||
<methodparam><modifier>const</modifier><type>char *</type><parameter>string</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>BString &</type><methodname>operator=</methodname>
|
||||
<methodparam><type>char</type><parameter>string</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bstring_operator_append">
|
||||
<title>+= (append)</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>BString &</type><methodname>operator+=</methodname>
|
||||
<methodparam><modifier>const</modifier><type>BString &</type><parameter>string</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>BString &</type><methodname>operator+=</methodname>
|
||||
<methodparam><modifier>const</modifier><type>char *</type><parameter>string</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>BString &</type><methodname>operator+=</methodname>
|
||||
<methodparam><modifier>const</modifier><type>char</type><parameter>character</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="bstring_operator_comparison">
|
||||
<title><, <=, ==, >, >=, != (comparison)</title>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>BString &</type><methodname>operator<</methodname>
|
||||
<methodparam><modifier>const</modifier><type>BString &</type><parameter>string</parameter></methodparam>
|
||||
<modifier>const</modifier>
|
||||
</methodsynopsis>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>BString &</type><methodname>operator<</methodname>
|
||||
<methodparam><modifier>const</modifier><type>char *</type><parameter>string</parameter></methodparam>
|
||||
<modifier>const</modifier>
|
||||
</methodsynopsis>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>BString &</type><methodname>operator<=</methodname>
|
||||
<methodparam><modifier>const</modifier><type>BString &</type><parameter>string</parameter></methodparam>
|
||||
<modifier>const</modifier>
|
||||
</methodsynopsis>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>BString &</type><methodname>operator<=</methodname>
|
||||
<methodparam><modifier>const</modifier><type>char *</type><parameter>string</parameter></methodparam>
|
||||
<modifier>const</modifier>
|
||||
</methodsynopsis>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>BString &</type><methodname>operator==</methodname>
|
||||
<methodparam><modifier>const</modifier><type>BString &</type><parameter>string</parameter></methodparam>
|
||||
<modifier>const</modifier>
|
||||
</methodsynopsis>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>BString &</type><methodname>operator==</methodname>
|
||||
<methodparam><modifier>const</modifier><type>char *</type><parameter>string</parameter></methodparam>
|
||||
<modifier>const</modifier>
|
||||
</methodsynopsis>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>BString &</type><methodname>operator>=</methodname>
|
||||
<methodparam><modifier>const</modifier><type>BString &</type><parameter>string</parameter></methodparam>
|
||||
<modifier>const</modifier>
|
||||
</methodsynopsis>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>BString &</type><methodname>operator>=</methodname>
|
||||
<methodparam><modifier>const</modifier><type>char *</type><parameter>string</parameter></methodparam>
|
||||
<modifier>const</modifier>
|
||||
</methodsynopsis>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>BString &</type><methodname>operator></methodname>
|
||||
<methodparam><modifier>const</modifier><type>BString &</type><parameter>string</parameter></methodparam>
|
||||
<modifier>const</modifier>
|
||||
</methodsynopsis>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>BString &</type><methodname>operator></methodname>
|
||||
<methodparam><modifier>const</modifier><type>char *</type><parameter>string</parameter></methodparam>
|
||||
<modifier>const</modifier>
|
||||
</methodsynopsis>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>BString &</type><methodname>operator!=</methodname>
|
||||
<methodparam><modifier>const</modifier><type>BString &</type><parameter>string</parameter></methodparam>
|
||||
<modifier>const</modifier>
|
||||
</methodsynopsis>
|
||||
|
||||
<methodsynopsis>
|
||||
<type>BString &</type><methodname>operator!=</methodname>
|
||||
<methodparam><modifier>const</modifier><type>char *</type><parameter>string</parameter></methodparam>
|
||||
<modifier>const</modifier>
|
||||
</methodsynopsis>
|
||||
</sect3>
|
||||
</sect2>
|
||||
@@ -1,35 +0,0 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
||||
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
|
||||
|
||||
<!ENTITY archivable SYSTEM "Archivable.xml">
|
||||
<!ENTITY autolock SYSTEM "Autolock.xml">
|
||||
<!ENTITY blockcache SYSTEM "BlockCache.xml">
|
||||
<!ENTITY dataio SYSTEM "DataIO.xml">
|
||||
<!ENTITY flattenable SYSTEM "Flattenable.xml">
|
||||
<!ENTITY list SYSTEM "List.xml">
|
||||
<!ENTITY locker SYSTEM "Locker.xml">
|
||||
<!ENTITY mallocio SYSTEM "MallocIO.xml">
|
||||
<!ENTITY memoryio SYSTEM "MemoryIO.xml">
|
||||
<!ENTITY positionio SYSTEM "PositionIO.xml">
|
||||
<!ENTITY stopwatch SYSTEM "StopWatch.xml">
|
||||
<!ENTITY string SYSTEM "String.xml">
|
||||
|
||||
]>
|
||||
|
||||
<sect1 id="supportapi">
|
||||
<title>Support Kit API</title>
|
||||
|
||||
&archivable;
|
||||
&autolock;
|
||||
&dataio;
|
||||
&blockcache;
|
||||
&flattenable;
|
||||
&list;
|
||||
&locker;
|
||||
&mallocio;
|
||||
&memoryio;
|
||||
&positionio;
|
||||
&stopwatch;
|
||||
&string;
|
||||
</sect1>
|
||||
@@ -1,48 +0,0 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
||||
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
|
||||
|
||||
]>
|
||||
|
||||
<sect1 id="support-intro">
|
||||
<title>Introduction</title>
|
||||
|
||||
<para>
|
||||
The <emphasis>Support Kit</emphasis> is an assortment of easy to use classes which allow a programmer to quickly extend their applications without re-writing much common functionality. Many benefits can arrise from using these classes when one starts to extend an application in the future. Functionality includes:
|
||||
<itemizedlist>
|
||||
<listitem><para>
|
||||
Threading utility classes:
|
||||
<itemizedlist>
|
||||
<listitem><para><link linkend="blocker">BLocker</link> and <link linkend="bautolock">BAutoLock</link></para></listitem>
|
||||
<listitem><para> "Thread Local Storage" </para></listitem>
|
||||
</itemizedlist>
|
||||
</para></listitem>
|
||||
<listitem><para>Archiving and IO:</para>
|
||||
<itemizedlist>
|
||||
<listitem><para><link linkend="barchivable">BArchivable</link></para></listitem>
|
||||
<listitem><para><link linkend="bflattenable">BFlattenable</link></para></listitem>
|
||||
<listitem><para><link linkend="bdataio">BDataIO</link></para>
|
||||
<itemizedlist>
|
||||
<listitem><para><link linkend="bpositionio">BPositionIO</link></para>
|
||||
<itemizedlist>
|
||||
<listitem><para><link linkend="bmemoryio">BMemoryIO</link></para></listitem>
|
||||
<listitem><para><link linkend="bmallocio">BMallocIO</link></para></listitem>
|
||||
</itemizedlist>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</listitem>
|
||||
</itemizedlist></listitem>
|
||||
<listitem><para>
|
||||
Container classes:
|
||||
<itemizedlist>
|
||||
<listitem><para><link linkend="bblockcache">BBlockCache</link></para></listitem>
|
||||
<listitem><para><link linkend="blist">BList</link></para></listitem>
|
||||
<listitem><para><link linkend="bstring">BString</link></para></listitem>
|
||||
</itemizedlist>
|
||||
</para></listitem>
|
||||
<listitem><para><link linkend="bstopwatch">BStopWatch</link></para></listitem>
|
||||
<listitem><para> Common types and constants </para></listitem>
|
||||
<listitem><para> Error codes for all kits </para></listitem>
|
||||
</itemizedlist>
|
||||
</para>
|
||||
</sect1>
|
||||
@@ -1,9 +0,0 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
|
||||
<chapter id="st-supportkit">
|
||||
<title>The Support Kit</title>
|
||||
|
||||
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="support/intro.xml" />
|
||||
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="support/api.xml" />
|
||||
</chapter>
|
||||
|
||||
@@ -1,13 +0,0 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
||||
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
|
||||
|
||||
]>
|
||||
|
||||
<sect1 id="translation-intro">
|
||||
<title>Introduction</title>
|
||||
|
||||
<para>
|
||||
The <emphasis>Translation Kit</emphasis> gives the user the ability to convert media from one format into a number of target formats. To accomplish this it provides functionality in the form of BTranslatorRoster for the act, management and configuration of the translation and BTranslator for the creation of new translators between additional formats.
|
||||
</para>
|
||||
</sect1>
|
||||
@@ -1,8 +0,0 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
|
||||
<chapter id="st-translationkit">
|
||||
<title>The Translation Kit</title>
|
||||
|
||||
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="translation/intro.xml" />
|
||||
</chapter>
|
||||
|
||||
@@ -1,463 +0,0 @@
|
||||
#!/bin/perl
|
||||
|
||||
# headerSampler.pl, Copyright (C) 1997, Mizutori Tetsuya
|
||||
# <[email protected]>
|
||||
# January 7, 1997, February 4, 1997.
|
||||
# Usage:
|
||||
# Drag and drop the C++ header files onto this 'header.pl' script
|
||||
|
||||
use integer;
|
||||
#use strict ('subs','vars');
|
||||
|
||||
my $gMAC = ( $ENV{'HOME'} =~ /^$/ );
|
||||
#if ( $gMAC ) { print "I love Macintosh.\n"; }
|
||||
my $gScope = "";
|
||||
my $gSentence = "";
|
||||
my $gDocbookpath = "";
|
||||
|
||||
# if the command line includes no file list, then prompt the choose dialog.
|
||||
#push(@ARGV, ChooseFile()) unless defined @ARGV;
|
||||
|
||||
DoMain();
|
||||
|
||||
ExitToShell();
|
||||
|
||||
#
|
||||
|
||||
################
|
||||
# DoMain
|
||||
################
|
||||
|
||||
sub DoMain {
|
||||
my $filepath;
|
||||
my $countFiles = 0;
|
||||
|
||||
$filepath = $ARGV[0];
|
||||
$gDocbookpath = $ARGV[1];
|
||||
# foreach $filepath (@ARGV) {
|
||||
my ($creator,$type) = GetFileInfo($filepath);
|
||||
|
||||
$countFiles++;
|
||||
#print "[$countFiles] = ['$creator','$type'] $filepath\n";
|
||||
|
||||
# skip if the file is not 'TEXT' nor '*.h'.
|
||||
next if ($type ne 'TEXT');
|
||||
next unless ($filepath =~ /\.h$/);
|
||||
|
||||
$gScope = "private:";
|
||||
$gSentence = "";
|
||||
@gComment = ();
|
||||
$gIsIgnoring = 0;
|
||||
|
||||
open(IN, $filepath) || die "Can't open '$filepath'";
|
||||
while (<IN>) {
|
||||
chomp;
|
||||
HandleTextline();
|
||||
}
|
||||
close IN;
|
||||
# }
|
||||
}
|
||||
|
||||
|
||||
################
|
||||
# HandleTextline
|
||||
################
|
||||
|
||||
sub HandleTextline {
|
||||
|
||||
# fetch the commant part if it exists.
|
||||
if ( m/\/\/.*$/ ) { $gComment[$#gComment + 1] = $&; }
|
||||
|
||||
# ignore the comment part in the line.
|
||||
s/^(.*)\/\/.*$/$1/;
|
||||
|
||||
# trim the line.
|
||||
s/^[ \t]+//;
|
||||
s/[ \t]+$//;
|
||||
|
||||
SWITCH: {
|
||||
|
||||
# skip 'typedef' or 'struct' region.
|
||||
(/^typedef/ || /^struct/ || /^namespace/) && do {
|
||||
$gIsIgnoring = 1;
|
||||
if ( /^namespace.*}$/ ) { $gIsIgnoring = 0; }
|
||||
last SWITCH;
|
||||
};
|
||||
|
||||
# skip this line if it begins with "#ifdef", "#endif", and others.
|
||||
/^#/ && do {
|
||||
@gComment = ();
|
||||
last SWITCH;
|
||||
};
|
||||
|
||||
# ignore this line if it begins with "public" and other keywords.
|
||||
(/^public:/ || /^protected:/ || /^private:/) && do {
|
||||
$gScope = $_;
|
||||
$gSentence = "";
|
||||
@gComment = ();
|
||||
last SWITCH;
|
||||
};
|
||||
|
||||
# skip this line if it ends with "}???;".
|
||||
/\}.*;$/ && do {
|
||||
$gSentence = "";
|
||||
@gComment = ();
|
||||
$gIsIgnoring = 0;
|
||||
last SWITCH;
|
||||
};
|
||||
|
||||
# skip this line if it ends with "}???". for namespace
|
||||
/\}$/ && do {
|
||||
$gSentence = "";
|
||||
@gComment = ();
|
||||
$gIsIgnoring = 0;
|
||||
last SWITCH;
|
||||
};
|
||||
|
||||
# test if end of 'typedef' or 'struct' region.
|
||||
($gIsIgnoring) && do {
|
||||
last SWITCH;
|
||||
};
|
||||
|
||||
# append this line to my sentence.
|
||||
do {
|
||||
$gSentence .= "\t" unless $gSentence =~ /^$/;
|
||||
$gSentence .= $_;
|
||||
};
|
||||
|
||||
# handle my sentence if the line ends with ";".
|
||||
/;$/ && do {
|
||||
$_ = $gSentence;
|
||||
ApplySentence();
|
||||
$gSentence = "";
|
||||
@gComment = ();
|
||||
last SWITCH;
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
################
|
||||
# ApplySentence
|
||||
################
|
||||
|
||||
sub ApplySentence {
|
||||
# my ($textline) = @_;
|
||||
|
||||
# eliminate the duplicate spaces to a blank space.
|
||||
s/[ \t]+/ /g;
|
||||
|
||||
# eliminate the ";" character at the tail end.
|
||||
s/[ ]*;$//;
|
||||
|
||||
#if ( s/[ ]*const$// ) { PrintFunction(); } # if the function has 'const'modifier.
|
||||
#elsif ( /\)$/ ) { PrintFunction(); }
|
||||
if ( /\)/ ) { PrintFunction(); }
|
||||
#else { PrintVariable(); }
|
||||
|
||||
}
|
||||
|
||||
|
||||
################
|
||||
# PrintFunction
|
||||
################
|
||||
|
||||
sub PrintFunction {
|
||||
# print a comment.
|
||||
# my $textline;
|
||||
# if ( $#gComment >= 0 ) {
|
||||
# foreach $textline (@gComment) {
|
||||
# print "\t\t$textline\n";
|
||||
# }
|
||||
# }
|
||||
|
||||
if (! ($gScope =~ /^public/ )) {
|
||||
return;
|
||||
}
|
||||
|
||||
# print a scope sign.
|
||||
#print WhichScope();
|
||||
|
||||
# print "#$_\n";
|
||||
my $functype, $funcname, $funcargs;
|
||||
|
||||
# split line to <NAME{$`}> ( <ARGS{$1}> ) parts.
|
||||
m/[ ]*\([ ]*(.*)[ ]*\)[ ]*([const]*)/;
|
||||
$funcname = $`;
|
||||
$funcargs = $1;
|
||||
$funcconst = $2;
|
||||
$funcname =~ s/[ ]+$//;
|
||||
$funcargs =~ s/[ ]+$//;
|
||||
|
||||
# handle func name.
|
||||
split(/[ ]+/,$funcname);
|
||||
$funcname = pop();
|
||||
$functype = join(' ', @_);
|
||||
|
||||
if ( $funcname =~ /^\*/ ) {
|
||||
$funcname = $';
|
||||
$functype = $functype . " *";
|
||||
}
|
||||
|
||||
# handle func arg list.
|
||||
split(/[ ]*,[ ]*/, $funcargs);
|
||||
my @args = @_;
|
||||
for (@args) {
|
||||
$paramconst = "";
|
||||
$paraminit = "";
|
||||
if ( /const*/ ) { $paramconst = "<modifier>const</modifier>"; }
|
||||
if ( /[ ]*=[ ]*/ ) { $paraminit = "<initializer>". $' ."</initializer>" ; $_ = $`; } # for default value; ex. (short X = 100)
|
||||
split(/[ ]+/);
|
||||
$paramname = pop();
|
||||
$paramtype = pop();
|
||||
if ( $paramname =~ /^\*/ ) {
|
||||
$paramname = $';
|
||||
$paramtype .= " *";
|
||||
}
|
||||
$_ = $paramconst . "<type>" . $paramtype . "</type> <parameter>" . $paramname . "</parameter>" . $paraminit;
|
||||
}
|
||||
$funcargs = join('</methodparam><methodparam>', @args);
|
||||
|
||||
if ($functype) {
|
||||
$_ = $functype;
|
||||
$funcmod = "";
|
||||
if ( s/^virtual[ ]*// ) {
|
||||
$funcmod .= "virtual"
|
||||
}
|
||||
if ( s/^static[ ]*// ) {
|
||||
if ( $funcmod =~ /^$/ ) {
|
||||
$funcmod .= " ";
|
||||
}
|
||||
$funcmod .= "static"
|
||||
}
|
||||
if ($funcmod) {
|
||||
$funcmod = "<modifier>" . $funcmod . "</modifier>";
|
||||
}
|
||||
if ( /^void/ ) {
|
||||
$functype = $funcmod . "<void/>"
|
||||
} else {
|
||||
$typeconst = "";
|
||||
if ( /^const / ) { $typeconst = "<modifier>const</modifier>"; $_ = $'; }
|
||||
$functype = $funcmod . $typeconst . "<type>" . $_ . "</type>"
|
||||
}
|
||||
}
|
||||
if ($funcconst) {
|
||||
$funcconst = " " . "<modifier>" . $funcconst . "</modifier>"
|
||||
}
|
||||
if ($funcargs) {
|
||||
$funcargs = "<methodparam>" . $funcargs . "</methodparam>"
|
||||
} else {
|
||||
$funcargs = "<void/>"
|
||||
}
|
||||
$_ = $functype . " <methodname>" . $funcname . "</methodname> " . $funcargs . $funcconst;
|
||||
ValidateDocbook();
|
||||
# print "FUNC = TYPE($funcname)+NAME($funcname)+ARGS($funcargs)\n";
|
||||
# print $funcname . "\t" x CalcTabs($funcname,5) . $functype . "(" . $funcargs . ")";
|
||||
# print "\n";
|
||||
}
|
||||
|
||||
################
|
||||
# ValidateDocbook
|
||||
################
|
||||
|
||||
sub ValidateDocbook {
|
||||
|
||||
open(IN2, $gDocbookpath) || die "Can't open '$gDocbookpath'";
|
||||
|
||||
# we drop every space for the moment
|
||||
s/[\t ]//g;
|
||||
|
||||
my $line = "";
|
||||
my $pattern = $_;
|
||||
my $found = 0;
|
||||
my $ignoring = 1;
|
||||
|
||||
while (<IN2>) {
|
||||
chomp;
|
||||
s/^[\t ]+//;
|
||||
s/[\t ]+$//;
|
||||
s/[\t ]//g;
|
||||
if ($ignoring) {
|
||||
if ( m/<methodsynopsis>/ ) {
|
||||
$line = $';
|
||||
$ignoring = 0;
|
||||
}
|
||||
} else {
|
||||
$line .= $_;
|
||||
if ( index($line, $pattern) >= 0 ) {
|
||||
$found = 1;
|
||||
break;
|
||||
}
|
||||
if ( $line =~ /<\/methodsynopsis>/ ) {
|
||||
$line = "";
|
||||
$ignoring = 1;
|
||||
}
|
||||
}
|
||||
}
|
||||
if ( $found == 0 ) {
|
||||
$pattern =~ s/\*/ \*/g;
|
||||
print "<methodsynopsis>".$pattern . "</methodsynopsis>\n" ;
|
||||
}
|
||||
close IN2;
|
||||
}
|
||||
|
||||
|
||||
################
|
||||
# PrintVariable
|
||||
################
|
||||
|
||||
sub PrintVariable {
|
||||
|
||||
# print a scope sign.
|
||||
print WhichScope();
|
||||
|
||||
# print "#$_\n";
|
||||
my $vartype;
|
||||
my $varname = $_;
|
||||
my $varargs = "";
|
||||
|
||||
# split line to <NAME{$`}> [ <ARGS{$1}> ] parts.
|
||||
if ( m/[ ]*\[[ ]*(.*)[ ]*\][ ]*/ ) {
|
||||
$varname = $`;
|
||||
$varargs = $1;
|
||||
$varname =~ s/[ ]+$//;
|
||||
$varargs =~ s/[ ]+$//;
|
||||
}
|
||||
|
||||
split(/[ ]+/,$varname);
|
||||
my $vartype = join(' ', @_[0..($#_ - 1)]);
|
||||
my $varname = $_[$#_];
|
||||
|
||||
# print variable definition
|
||||
print $vartype . "\t" x CalcTabs($vartype,5). $varname;
|
||||
if ( $varargs ne "" ) { print "[" . $varargs . "]"; }
|
||||
|
||||
# print a comment.
|
||||
if ( $#gComment >= 0 ) {
|
||||
print "\t" x CalcTabs($varname,4);
|
||||
print join("\t",@gComment);
|
||||
}
|
||||
|
||||
print "\n";
|
||||
}
|
||||
|
||||
|
||||
################
|
||||
# WhichScope()
|
||||
################
|
||||
|
||||
sub WhichScope {
|
||||
# my ($textline) = @_;
|
||||
my $key;
|
||||
my $str;
|
||||
|
||||
SWITCH: {
|
||||
( s/^virtual[ ]*// ) && do { $key = "v"; last SWITCH; };
|
||||
( s/^static[ ]*// ) && do { $key = "s"; last SWITCH; };
|
||||
do { $key = "."; last SWITCH; }
|
||||
};
|
||||
|
||||
SWITCH: {
|
||||
($gScope =~ /^public/ ) && do { $str = "=" . $key . "="; last SWITCH; };
|
||||
($gScope =~ /^protected/ ) && do { $str = ">" . $key . ">"; last SWITCH; };
|
||||
($gScope =~ /^private/ ) && do { $str = "(" . $key . ")"; last SWITCH; };
|
||||
do { $str = " " . $key . " "; last SWITCH; };
|
||||
};
|
||||
|
||||
return $str . "\t";
|
||||
}
|
||||
|
||||
|
||||
################
|
||||
# StringWidth
|
||||
################
|
||||
|
||||
sub StringWidth {
|
||||
my ($str) = @_;
|
||||
|
||||
# width table of 10-point Geneva font
|
||||
my %width_table = (
|
||||
' '=> 3, '!'=> 4, '"'=> 5, '#'=> 9, '\$'=> 7, '%'=>10, '&'=> 8, '\''=> 3,
|
||||
'('=> 6, ')'=> 6, '*'=> 7, '+'=> 8, ','=> 4, '-'=> 7, '.'=> 3, '/'=> 6,
|
||||
'0'=> 7, '1'=> 7, '2'=> 7, '3'=> 7, '4'=> 7, '5'=> 7, '6'=> 7, '7'=> 7,
|
||||
'8'=> 7, '9'=> 7, ':'=> 3, ';'=> 4, '<'=> 5, '='=> 7, '>'=> 5, '?'=> 7,
|
||||
'@'=> 9, 'A'=> 6, 'B'=> 7, 'C'=> 6, 'D'=> 7, 'E'=> 6, 'F'=> 6, 'G'=> 6,
|
||||
'H'=> 7, 'I'=> 4, 'J'=> 6, 'K'=> 7, 'L'=> 6, 'M'=> 9, 'N'=> 7, 'O'=> 6,
|
||||
'P'=> 7, 'Q'=> 6, 'R'=> 7, 'S'=> 6, 'T'=> 6, 'U'=> 7, 'V'=> 6, 'W'=>10,
|
||||
'X'=> 6, 'Y'=> 6, 'Z'=> 6, '['=> 5, '\\'=> 5, ']'=> 5, '^'=> 5, '_'=> 7,
|
||||
'`'=> 4, 'a'=> 5, 'b'=> 6, 'c'=> 5, 'd'=> 5, 'e'=> 5, 'f'=> 4, 'g'=> 5,
|
||||
'h'=> 6, 'i'=> 4, 'j'=> 5, 'k'=> 6, 'l'=> 4, 'm'=> 9, 'n'=> 6, 'o'=> 5,
|
||||
'p'=> 6, 'q'=> 5, 'r'=> 6, 's'=> 5, 't'=> 4, 'u'=> 6, 'v'=> 6, 'w'=> 8,
|
||||
'x'=> 6, 'y'=> 6, 'z'=> 5, '{'=> 5, '|'=> 4, '}'=> 5, '~'=> 7
|
||||
);
|
||||
|
||||
# my $tab_width = 4 * $width_table{'0'};
|
||||
|
||||
my $sum = 0;
|
||||
my $c;
|
||||
|
||||
foreach $c ( split(//,$str) ) {
|
||||
$sum += $width_table{$c};
|
||||
# print "'$c' =>$width_table{$c}/$sum\n";
|
||||
}
|
||||
|
||||
return $sum;
|
||||
}
|
||||
|
||||
|
||||
################
|
||||
# CalcTabs
|
||||
################
|
||||
|
||||
sub CalcTabs {
|
||||
my ($str,$tabn) = @_;
|
||||
my $tab_width = 4 * StringWidth('0');
|
||||
my $tab_position = $tabn * $tab_width;
|
||||
my $skip_dots = $tab_position - StringWidth($str);
|
||||
my $more_tabs = 1;
|
||||
|
||||
if ( $skip_dots > 0 ) {
|
||||
$more_tabs += ($skip_dots - 1) / $tab_width;
|
||||
}
|
||||
|
||||
# print "["; print "$more_tabs:$skip_dots"; print "]";
|
||||
|
||||
return $more_tabs;
|
||||
}
|
||||
|
||||
|
||||
################
|
||||
# ExitToShell()
|
||||
################
|
||||
# Macintosh specific routine
|
||||
|
||||
sub ExitToShell {
|
||||
|
||||
# if the runtime environment is a Macintosh.
|
||||
&MacPerl'Quit(1) if $gMAC;
|
||||
|
||||
# else then it is a Unix.
|
||||
exit(0);
|
||||
}
|
||||
|
||||
|
||||
################
|
||||
# GetFileInfo()
|
||||
################
|
||||
# Macintosh specific routine
|
||||
# Returns a list ($creator,$type)
|
||||
|
||||
sub GetFileInfo {
|
||||
my ($filepath) = @_;
|
||||
|
||||
# if the runtime environment is a Macintosh.
|
||||
return &MacPerl'GetFileInfo($filepath) if $gMAC;
|
||||
|
||||
# else then it is a Unix and if the file is a text file.
|
||||
return ('????', 'TEXT') if -T $filepath;
|
||||
|
||||
# otherwise returns nil.
|
||||
return ('????', '????');
|
||||
}
|
||||
|
||||
### end of script ###
|
||||
Reference in New Issue
Block a user