1/*! 2 \mainpage Welcome to the Haiku Book 3 4 Below you will find documentation on the Application Programming 5 Interface (API) of the Haiku operating system. This API describes 6 the internals of the operating system allowing developers to write 7 native C++ applications and device drivers. See the 8 <a href="https://api.haiku-os.org">online version</a> for the most 9 updated version of this document. If you would like to help contribute 10 contact the <a href="https://www.freelists.org/list/haiku-doc">documentation 11 mailing list</a>. For guidelines on how to help document the API see 12 the \link apidoc Documenting the API\endlink page. A list of 13 contributors can be found \ref credits page. Documenting the API is 14 an ongoing process so contributions are greatly appreciated. 15 16 The Haiku API is based on the BeOS R5 API but changes and additions have 17 been included where appropriate. Important compatibility differences are 18 detailed on the \ref compatibility page. New classes and methods 19 and incompatible API changes to the BeOS R5 API are noted in the 20 appropriate sections. 21 22 A complete reference to the BeOS R5 API is available on the web in 23 <a href="https://haiku-os.org/legacy-docs/bebook/">The Be Book</a>. 24 The Be Book is used with permission from 25 <a href="https://www.access-company.com/">Access Co.</a>, the current 26 owners of Be's intellectual property. 27 28 \section book_kits Kits and Servers 29 30 The API is split into several kits and servers each detailing a different 31 aspect of the operating system. 32 - The \ref app is the starting point for developing applications 33 and includes classes for messaging and for interacting with 34 the rest of the system. 35 - The \ref game provides classes for producing game sounds and 36 working with full screen apps. 37 - The \ref interface is used to create responsive and attractive 38 graphical user interfaces building on the messaging facilities 39 provided by the Application Kit. 40 - A \link interface_intro general introduction \endlink to the 41 Interface Kit. 42 - The \link layout_intro Layout API \endlink is a new addition 43 to the Interface Kit in Haiku which provides resources to 44 layout your application flexibly and easily. 45 - The \ref locale includes classes to localize your application to 46 different languages, timezones, number formatting conventions and 47 much more. 48 - The \ref mail includes classes to work with e-mail files, folders, 49 protocols, and filters, as part of Haiku's unique mail handling system. 50 - The \ref media provides a unified and consistent interface for media 51 streams and applications to intercommunicate. 52 - The \ref midi2 describes an interface to generating, processing, 53 and playing music in MIDI format. For reference documentation on the 54 \ref midi1 is also included. 55 - The \ref network handles everything network related, from interface 56 IP address settings to HTTP connections. 57 - The \ref storage is a collection of classes that deal with storing and 58 retrieving information from disk. 59 - The \ref support contains support classes to use in your application 60 including resources for thread safety, IO, and serialization. 61 - The \ref translation provides a framework for converting data streams 62 between media formats. 63 64 \section book_special_topics Special Topics 65 66 - \ref libroot 67 - \ref drivers 68 - \ref keyboard 69 - \ref json 70 - \ref netservices 71*/ 72 73///// Define main kits ///// 74 75/*! 76 \defgroup app Application Kit 77 \brief The Application Kit is the starting point for writing native Haiku 78 GUI applications. 79 80 The application kit is exactly what its name suggests — it is the 81 basis of Haiku applications. You should first read through this document 82 and the references here before moving on to the other parts of the API. 83 84 The Application Kit classes can be divided into two groups: the messaging 85 classes and the system interaction classes. The larger of the two groups is 86 the messaging classes. Since the Haiku API relies on pervasive 87 multithreading messaging is an essential topic for any application. Have a 88 look at the \link app_messaging Introduction to Messaging \endlink for more 89 information. 90 91 The following messaging classes which allow you to easily and securely 92 communicate between threads. 93 - BHandler 94 - BInvoker 95 - BLooper 96 - BMessage 97 - BMessageFilter 98 - BMessageQueue 99 - BMessageRunner 100 - BMessenger 101 102 The second group is the system interaction classes. These classes 103 provide hooks for your application to interact with the rest of the system. 104 The most important class in this group is BApplication. Below is a list of 105 all system interaction classes: 106 - BApplication 107 - BClipboard 108 - BCursor 109 - BLaunchRoster 110 - BNotification 111 - BPropertyInfo 112 - BRoster 113 114 A third special category is the \link app_keystore Password and Key storage 115 API:\endlink 116 - BKey 117 - BKeyStore 118 119 120 \defgroup game Game Kit 121 \brief The Game Kit provides classes for producing game sounds and 122 working with full screen apps. 123 124 125 \defgroup interface Interface Kit 126 \brief API for displaying a graphical user interface. 127 128 \defgroup locale Locale Kit 129 \brief Collection of classes for localizing applications. 130 131 \defgroup mail Mail Kit 132 \brief API for working with e-mail messages and protocols. 133 134 \defgroup media Media Kit 135 \brief Collection of classes that deal with audio and video. 136 137 \defgroup midi1 The old MIDI Kit (libmidi.so) 138 \brief The old MIDI kit. 139 140 141 \defgroup midi2 MIDI 2 Kit 142 \brief The Midi Kit is the API that implements support for generating, 143 processing, and playing music in MIDI format. 144 145 <A HREF="https://www.midi.org/">MIDI</A>, which stands for 'Musical 146 Instrument Digital Interface', is a well-established standard for 147 representing and communicating musical data. This document serves as 148 an overview. If you would like to see all the components, please look 149 at \link midi2 the list with classes \endlink. 150 151 \section book_midi2twokits A Tale of Two MIDI Kits 152 153 BeOS comes with two different, but compatible Midi Kits. This 154 documentation focuses on the "new" Midi Kit, or midi2 as we like to 155 call it, that was introduced with BeOS R5. The old kit, which we'll 156 refer to as midi1, is more complete than the new kit, but less powerful. 157 158 Both kits let you create so-called MIDI endpoints, but the endpoints 159 from midi1 cannot be shared between different applications. The midi2 160 kit solves that problem, but unlike midi1 it does not include a General 161 MIDI softsynth, nor does it have a facility for reading and playing 162 Standard MIDI Files. Don't worry: both kits are compatible and you can 163 mix-and-match them in your applications. 164 165 The main differences between the two kits: 166 - Instead of one BMidi object that both produces and consumes events, 167 we have BMidiProducer and BMidiConsumer. 168 - Applications are capable of sharing MIDI producers and consumers 169 with other applications via the centralized Midi Roster. 170 - Physical MIDI ports are now sharable without apps "stealing" events 171 from each other. 172 - Applications can now send/receive raw MIDI byte streams (useful if 173 an application has its own MIDI parser/engine). 174 - Channels are numbered 0–15, not 1–16 175 - Timing is now specified in microseconds rather than milliseconds. 176 177 \section book_midi2concepts Midi Kit Concepts 178 179 A brief overview of the elements that comprise the Midi Kit: 180 - \b Endpoints. This is what the Midi Kit is all about: sending MIDI 181 messages between endpoints. An endpoint is like a MIDI In or MIDI 182 Out socket on your equipment; it either receives information or it 183 sends information. Endpoints that send MIDI events are called 184 \b producers; the endpoints that receive those events are called 185 \b consumers. An endpoint that is created by your own application 186 is called \b local; endpoints from other applications are 187 \b remote. You can access remote endpoints using \b proxies. 188 - \b Filters. A filter is an object that has a consumer and a producer 189 endpoint. It reads incoming events from its consumer, performs some 190 operation, and tells its producer to send out the results. In its 191 current form, the Midi Kit doesn't provide any special facilities 192 for writing filters. 193 - \b Midi \b Roster. The roster is the list of all published producers 194 and consumers. By publishing an endpoint, you allow other 195 applications to talk to it. You are not required to publish your 196 endpoints, in which case only your own application can use them. 197 - \b Midi \b Server. The Midi Server does the behind-the-scenes work. 198 It manages the roster, it connects endpoints, it makes sure that 199 endpoints can communicate, and so on. The Midi Server is started 200 automatically when BeOS boots, and you never have to deal with it 201 directly. Just remember that it runs the show. 202 - \b libmidi. The BMidi* classes live inside two shared libraries: 203 libmidi.so and libmidi2.so. If you write an application that uses 204 old Midi Kit, you must link it to libmidi.so. Applications that use 205 the new Midi Kit must link to libmidi2.so. If you want to 206 mix-and-match both kits, you should also link to both libraries. 207 208 Here is a pretty picture: 209 210 \image html midi2concepts.png 211 212 \section book_midi2mediakit Midi Kit != Media Kit 213 214 Be chose not to integrate the Midi Kit into the Media Kit as another media 215 type, mainly because MIDI doesn't require any of the format negotiation that 216 other media types need. Although the two kits look similar -- both have a 217 "roster" for finding or registering "consumers" and "producers" -- there are 218 some very important differences. 219 220 The first and most important point to note is that BMidiConsumer and 221 BMidiProducer in the Midi Kit are \b NOT directly analogous to 222 BBufferConsumer and BBufferProducer in the Media Kit! In the Media Kit, 223 consumers and producers are the data consuming and producing properties 224 of a media node. A filter in the Media Kit, therefore, inherits from both 225 BBufferConsumer and BBufferProducer, and implements their virtual member 226 functions to do its work. 227 228 In the Midi Kit, consumers and producers act as endpoints of MIDI data 229 connections, much as media_source and media_destination do in the Media Kit. 230 Thus, a MIDI filter does not derive from BMidiConsumer and BMidiProducer; 231 instead, it contains BMidiConsumer and BMidiProducer objects for each of its 232 distinct endpoints that connect to other MIDI objects. The Midi Kit does not 233 allow the use of multiple virtual inheritance, so you can't create an object 234 that's both a BMidiConsumer and a BMidiProducer. 235 236 This also contrasts with the old Midi Kit's conception of a BMidi object, 237 which stood for an object that both received and sent MIDI data. In the new 238 Midi Kit, the endpoints of MIDI connections are all that matters. What lies 239 between the endpoints, i.e. how a MIDI filter is actually structured, is 240 entirely at your discretion. 241 242 Also, rather than use token structs like media_node to make connections 243 via the MediaRoster, the new kit makes the connections directly via the 244 BMidiProducer object. 245 246 \section book_midi2remotelocal Remote vs. Local Objects 247 248 The Midi Kit makes a distinction between remote and local MIDI objects. 249 You can only create local MIDI endpoints, which derive from either 250 BMidiLocalConsumer or BMidiLocalProducer. Remote endpoints are endpoints 251 that live in other applications, and you access them through BMidiRoster. 252 253 BMidiRoster only gives you access to BMidiEndpoints, BMidiConsumers, and 254 BMidiProducers. When you want to talk to remote MIDI objects, you do so 255 through the proxy objects that BMidiRoster provides. Unlike 256 BMidiLocalConsumer and BMidiLocalProducer, these classes do not provide a 257 lot of functions. That is intentional. In order to hide the details of 258 communication with MIDI endpoints in other applications, the Midi Kit must 259 hide the details of how a particular endpoint is implemented. 260 261 So what can you do with remote objects? Only what BMidiConsumer, 262 BMidiProducer, and BMidiEndpoint will let you do. You can connect 263 objects, get the properties of these objects -- and that's about it. 264 265 \section book_midi2lifespan Creating and Destroying Objects 266 267 The constructors and destructors of most midi2 classes are private, 268 which means that you cannot directly create them using the C++ 269 <CODE>new</CODE> operator, on the stack, or as globals. Nor can you 270 <CODE>delete</CODE> them. Instead, these objects are obtained through 271 BMidiRoster. The only two exceptions to this rule are BMidiLocalConsumer 272 and BMidiLocalProducer. These two objects may be directly created and 273 subclassed by developers. 274 275 \section book_midi2refcount Reference Counting 276 277 Each MIDI endpoint has a reference count associated with it, so that 278 the Midi Roster can do proper bookkeeping. When you construct a 279 BMidiLocalProducer or BMidiLocalConsumer endpoint, it starts with a 280 reference count of 1. In addition, BMidiRoster increments the reference 281 count of any object it hands to you as a result of 282 \link BMidiRoster::NextEndpoint() NextEndpoint() \endlink or 283 \link BMidiRoster::FindEndpoint() FindEndpoint() \endlink. 284 Once the count hits 0, the endpoint will be deleted. 285 286 This means that, to delete an endpoint, you don't call the 287 <CODE>delete</CODE> operator directly; instead, you call 288 \link BMidiEndpoint::Release() Release() \endlink. 289 To balance this call, there's also an 290 \link BMidiEndpoint::Acquire() Acquire() \endlink, in case you have two 291 disparate parts of your application working with the endpoint, and you 292 don't want to have to keep track of who needs to Release() the endpoint. 293 294 When you're done with any endpoint object, you must Release() it. 295 This is true for both local and remote objects. Repeat after me: 296 Release() when you're done. 297 298 \section book_midi2events MIDI Events 299 300 To make some actual music, you need to 301 \link BMidiProducer::Connect() Connect() \endlink your consumers to 302 your producers. Then you tell the producer to "spray" MIDI events to all 303 the connected consumers. The consumers are notified of these incoming 304 events through a set of hook functions. 305 306 The Midi Kit already provides a set of commonly used spray functions, 307 such as \link BMidiLocalProducer::SprayNoteOn() SprayNoteOn() \endlink, 308 \link BMidiLocalProducer::SprayControlChange() SprayControlChange() 309 \endlink, and so on. These correspond one-to-one with the message types 310 from the MIDI spec. You don't need to be a MIDI expert to use the kit, but 311 of course some knowledge of the protocol helps. If you are really hardcore, 312 you can also use the 313 \link BMidiLocalProducer::SprayData() SprayData() \endlink to send raw MIDI 314 events to the consumers. 315 316 At the consumer side, a dedicated thread invokes a hook function for every 317 incoming MIDI event. For every spray function, there is a corresponding hook 318 function, e.g. \link BMidiLocalConsumer::NoteOn() NoteOn() \endlink and 319 \link BMidiLocalConsumer::ControlChange() ControlChange() \endlink. 320 The hardcore MIDI fanatics among you will be pleased to know that you can 321 also tap into the \link BMidiLocalConsumer::Data() Data() \endlink hook and 322 get your hands dirty with the raw MIDI data. 323 324 \section book_midi2time Time 325 326 The spray and hook functions accept a bigtime_t parameter named "time". This 327 indicates when the MIDI event should be performed. The time is given in 328 microseconds since the computer booted. To get the current tick measurement, 329 you call the system_time() function from the Kernel Kit. 330 331 If you override a hook function in one of your consumer objects, it should 332 look at the time argument, wait until the designated time, and then perform 333 its action. The preferred method is to use the Kernel Kit's 334 <CODE>snooze_until()</CODE> function, which sends the consumer thread to 335 sleep until the requested time has come. (Or, if the time has already 336 passed, returns immediately.) 337 338 Like this: 339 340 \code 341void MyConsumer::NoteOn( 342 uchar channel, uchar note, uchar velocity, bigtime_t time) 343{ 344 snooze_until(time, B_SYSTEM_TIMEBASE); 345 ...do your thing... 346} 347 \endcode 348 349 If you want your producers to run in real time, i.e. they produce MIDI data 350 that needs to be performed immediately, you should pass time 0 to the spray 351 functions (which also happens to be the default value). Since time 0 has 352 already passed, <CODE>snooze_until()</CODE> returns immediately, and the 353 consumer will process the events as soon as they are received. 354 355 To schedule MIDI events for a performance time that lies somewhere in the 356 future, the producer must take into account the consumer's latency. 357 Producers should attempt to get notes to the consumer by or before 358 <I>(scheduled_performance_time - latency)</I>. The time argument is still 359 the scheduled performance time, so if your consumer has latency, it should 360 snooze like this before it starts to perform the events: 361 362 \code 363snooze_until(time - Latency(), B_SYSTEM_TIMEBASE); 364 \endcode 365 366 Note that a typical producer sends out its events as soon as it can; 367 unlike a consumer, it does not have to snooze. 368 369 \section book_midi2ports Other Timing Issues 370 371 Each consumer object uses a Kernel Kit port to receive MIDI events from 372 connected producers. The queue for this port is only 1 message deep. 373 This means that if the consumer thread is asleep in a 374 <CODE>snooze_until()</CODE>, it will not read its port. Consequently, 375 any producer that tries to write a new event to this port will block until 376 the consumer thread is ready to receive a new message. This is intentional, 377 because it prevents producers from generating and queueing up thousands of 378 events. 379 380 This mechanism, while simple, puts on the producer the responsibility 381 for sorting the events in time. Suppose your producer sends three Note 382 On events, the first on t + 0, the second on t + 4, and the third on t + 2. 383 This last event won't be received until after t + 4, so it will be two ticks 384 too late. If this sort of thing can happen with your producer, you should 385 somehow sort the events before you spray them. Of course, if you have two or 386 more producers connected to the same consumer, it is nearly impossible to 387 sort this all out (pardon the pun). So it is not wise to send the same kinds 388 of events from more than one producer to one consumer at the same time. 389 390 The article Introduction to MIDI, Part 2 in <A 391 HREF="https://open-beos.sourceforge.net/nsl.php?mode=display&id=36">OpenBeOS 392 Newsletter 36</A> describes this problem in more detail, and provides a 393 solution. Go read it now! 394 395 \section book_midi2filters Writing a Filter 396 397 A typical filter contains a consumer and a producer endpoint. It receives 398 events from the consumer, processes them, and sends them out again using the 399 producer. The consumer endpoint is a subclass of BMidiLocalConsumer, whereas 400 the producer is simply a BMidiLocalProducer, not a subclass. This is a 401 common configuration, because consumers work by overriding the event hooks 402 to do work when MIDI data arrives. Producers work by sending an event when 403 you call their member functions. You should hardly ever need to derive from 404 BMidiLocalProducer (unless you need to know when the producer gets connected 405 or disconnected, perhaps), but you'll always have to override one or more of 406 BMidiLocalConsumer's member functions to do something useful with incoming 407 data. 408 409 Filters should ignore the time argument from the spray and hook functions, 410 and simply pass it on unchanged. Objects that only filter data should 411 process the event as quickly as possible and be done with it. Do not 412 <CODE>snooze_until()</CODE> in the consumer endpoint of a filter! 413 414 \section book_midi2apidiffs API Differences 415 416 As far as the end user is concerned, the Haiku Midi Kit is mostly the same 417 as the BeOS R5 kits, although there are a few small differences in the API 418 (mostly bug fixes): 419 - BMidiEndpoint::IsPersistent() always returns false. 420 - The B_MIDI_CHANGE_LATENCY notification is now properly sent. The Be 421 kit incorrectly set be:op to B_MIDI_CHANGED_NAME, even though the 422 rest of the message was properly structured. 423 - If creating a local endpoint fails, you can still Release() the object 424 without crashing into the debugger. 425 426 \section book_midi2seealso See also 427 428 More about the Midi Kit: 429 - \ref Midi2Defs.h 430 - Be Newsletter Volume 3, Issue 47 - Motor Mix sample code 431 - Be Newsletter Volume 4, Issue 3 - Overview of the new kit 432 - <A HREF="https://haiku-os.org/documents/dev/introduction_to_midi_part_1">Newsletter 433 33</A>, Introduction to MIDI, Part 1 434 - <A HREF="https://haiku-os.org/documents/dev/introduction_to_midi_part_2">Newsletter 435 36</A>, Introduction to MIDI, Part 2 436 - Sample code and other goodies at the 437 <A HREF="https://haiku-os.org/about/teams/midi_kit">Haiku Midi Kit team page</A> 438 439 Information about MIDI in general: 440 - <A HREF="https://www.midi.org">MIDI Manufacturers Association</A> 441 - <A HREF="https://www.borg.com/~jglatt/tutr/miditutr.htm">MIDI Tutorials</A> 442 - <A HREF="https://www.borg.com/~jglatt/tech/midispec.htm">MIDI Specification</A> 443 - <A HREF="https://www.borg.com/~jglatt/tech/midifile.htm">Standard MIDI File Format</A> 444 - <A HREF="https://www.io.com/~jimm/midi_ref.html">Jim Menard's MIDI Reference</A> 445 446 447 \defgroup network Network Kit 448 \brief Classes that deal with all network connections and communications. 449 450 The Haiku Network Kit consists of: 451 - A modular, add-ons based network stack 452 - Two shared libraries, libnetwork.so and libnetapi.so 453 - A stack driver, acting as interface between the network stack and 454 libnetwork.so 455 - Basic network apps 456 - A modular GUI preflet 457 458 The libnet.so shared library is the way that BeOS R5 provided POSIX/BSD 459 API sockets to apps. Being binary compatible with BeOS R5 has made this 460 library implementation tedious. To counter this, the libnetapi.so shared 461 library was developed. It contains thin C++ classes wrapping the C 462 sockets POSIX/BSD API into these BNet* classes we're used under BeOS. 463 464 The stack driver is the interface between libnet.so and the real stack 465 behind it, hosted by the network stack kernel modules. Its purposes 466 include: 467 -# Providing sockets to file descriptors translation support 468 -# Providing support for select() on sockets 469 -# Loading the network stack on first access, and then keeping it for 470 further accesses 471 472 The following diagram illustrates the network stack design on Haiku: 473 474 \image html obos_net_stack_design_1.gif 475 476 The Network Kit includes a handful of useful networking related apps 477 including ping, ifconfig, route, traceroute, and arp. 478 479 See the User Guide for more information about the 480 <a href="https://haiku-os.org/docs/userguide/en/preferences/network.html">Network preferences app</a> 481 included as part of the Network Kit. 482 483 484 \defgroup storage Storage Kit 485 \brief Collection of classes that deal with storing and retrieving 486 information from disk. 487 488 489 \defgroup support Support Kit 490 \brief Collection of utility classes that are used throughout the API. 491 492 The Support Kit provides a handy set of classes that you can use in your 493 applications. These classes provide: 494 - \b Thread \b Safety. Haiku can execute multiple threads of an 495 application in parallel, letting certain parts of an application 496 continue when one part is stalled, as well as letting an application 497 process multiple pieces of data at the same time on multicore or 498 multiprocessor systems. However, there are times when multiple 499 threads desire to work on the same piece of data at the same time, 500 potentially causing a conflict where variables or pointers are 501 changed by one thread causing another to execute incorrectly. To 502 prevent this, Haiku implements a \"locking\" mechanism, allowing one 503 thread to \"lock out\" other threads from executing code that might 504 modify the same data. 505 - \b Archiving \b and \b IO. These classes allow a programmer to 506 convert objects into a form that can more easily be transferred to 507 other applications or stored to disk, as well as performing basic 508 input and output operations. 509 - \b Memory \b Allocation. This class allows a programmer to hand off 510 some of the duties of memory accounting and management. 511 - \b Common \b Datatypes. To avoid unnecessary duplication of code 512 and to make life easier for programmers, Haiku includes classes that 513 handle management of ordered lists and strings. 514 515 There are also a number of utility functions to time actions, play system 516 alert sounds, compare strings, and atomically manipulate integers. Have a 517 look at the overview, or go straight to the complete 518 \link support list of components \endlink of this kit. 519 520 \section book_overview Overview 521 - Thread Safety: 522 - BLocker provides a semaphore-like locking mechanism allowing for 523 recursive locks. 524 - BAutolock provides a simple method of automatically removing a 525 lock when a function ends. 526 - \ref TLS.h "Thread Local Storage" allows a global variable\'s 527 content to be sensitive to thread context. 528 - Archiving and IO: 529 - BArchivable provides an interface for \"archiving\" objects so 530 that they may be sent to other applications where an identical 531 copy will be recreated. 532 - BArchiver simplifies archiving of BArchivable hierarchies. 533 - BUnarchiver simplifies unarchiving hierarchies that have been 534 archived using BArchiver. 535 - BFlattenable provides an interface for \"flattening\" objects so 536 that they may be easily stored to disk. 537 - BDataIO provides an interface for generalized read/write streams. 538 - BPositionIO extends BDataIO to allow seeking within the data. 539 - BBufferIO creates a buffer and attaches it to a BPositionIO 540 stream, allowing for reduced load on the underlying stream. 541 - BMemoryIO allows operation on an already-existing buffer. 542 - BMallocIO creates and allows operation on a buffer. 543 - Memory Allocation: 544 - BBlockCache allows an application to allocate a \"pool\" of 545 memory blocks that the application can fetch and dispose of as 546 it pleases, letting the application make only a few large memory 547 allocations, instead of many small expensive allocations. 548 - Common Datatypes: 549 - BList allows simple ordered lists and provides common access, 550 modification, and comparison functions. 551 - BString allows strings and provides common access, modification, 552 and comparison functions. 553 - BStopWatch allows an application to measure the time an action takes. 554 - \ref support_globals "Global functions" 555 - \ref TypeConstants.h "Common types and constants" 556 - Error codes for all kits 557 558 559 \defgroup translation Translation Kit 560 \brief Provides a framework for converting data streams between media 561 formats. 562 563 564 \defgroup libtranslation (libtranslation.so) 565 566 \defgroup libbe (libbe.so) 567 568 569 \defgroup libroot (libroot.so) 570 \brief Implements the C and POSIX standard libraries. 571*/ 572 573///// Subgroups ///// 574 575/*! 576 \defgroup support_globals Global functions 577 \ingroup support 578 579 \defgroup layout Layout API 580 \brief Provides classes for automatically laying out UIs. 581 \ingroup interface 582*/ 583 584 585///// Special Topics ///// 586 587/*! 588 \defgroup drivers Device Drivers 589 590 \defgroup json Json Handling 591 \brief Provides for parsing and writing of data in Json encoding. 592*/ 593 594 595#if __cplusplus >= 201703L 596/*! 597 \defgroup netservices Experimental Network Services Support 598 \brief Experimental API to do higher level network requests 599 600 This API currently is marked as experimental. It is part of the 601 <code>BPrivate::Network</code> namespace, the header files are found at 602 <code>headers\\private\\netservices2</code>, and you have to link your 603 application to <code>libnetservices2.a</code>. The new API is only 604 available for modern platforms (x86 and x86_64), and not for the legacy 605 platform (x86_gcc2). The compiler needs to support C++17 or higher. 606 607 <h3>Asynchronous handling of the result.</h3> 608 609 In GUI applications, networking operations are often triggered by a user action. For example, 610 downloading a file will be initiated by the user clicking a button. When you initiate that 611 action in the window's thread, and you block the message loop until the request is finished, 612 the user will be left with a non-responsive UI. That is why one would usually run a network 613 request asynchronously. And instead of checking the status every few CPU cycles, you'd want 614 to be proactively informed when something important happens, like the progress of the download 615 or a signal when the request is finished. 616 617 The Network Services kit support using the Haiku API's Looper and Handler system to keep you up 618 to date about relevant events that happen to the requests. 619 620 The following messages are available for all requests (HTTP and other). The messages below are 621 in the order that they will arrive (when applicable). 622 623 <table> 624 <tr> 625 <th>Message Constant</th> 626 <th>Description</th> 627 <th>Applies to</th> 628 <th> Additional Data</th> 629 </tr> 630 <tr> 631 <td>\ref BPrivate::Network::UrlEvent::HostNameResolved "UrlEvent::HostNameResolved"</td> 632 <td> 633 The hostname has been resolved. This message is even sent when you set an 634 IP-address in the URL object 635 </td> 636 <td>All protocols that use network connections.</td> 637 <td> 638 \ref BPrivate::Network::UrlEventData::Id "UrlEventData::Id" \c int32 <br/> 639 \ref BPrivate::Network::UrlEventData::HostName "UrlEventData::HostName" 640 \ref BString 641 </td> 642 </tr> 643 <tr> 644 <td>\ref BPrivate::Network::UrlEvent::ConnectionOpened "UrlEvent::ConnectionOpened"</td> 645 <td> 646 The connection to the remote server is opened. After this event, data will be 647 written. 648 </td> 649 <td>All protocols that use network connections.</td> 650 <td> 651 \ref BPrivate::Network::UrlEventData::Id "UrlEventData::Id" \c int32 652 </td> 653 </tr> 654 <tr> 655 <td>\ref BPrivate::Network::UrlEvent::UploadProgress "UrlEvent::UploadProgress"</td> 656 <td> 657 If there is a request body to be sent, this informs you of the progress. When the 658 total size of the request body is known, this will be part of the message. 659 </td> 660 <td> 661 All protocols that use network connections and support writing data to the server 662 (like HTTP(S)). 663 </td> 664 <td> 665 \ref BPrivate::Network::UrlEventData::Id "UrlEventData::Id" \c int32 <br/> 666 \ref BPrivate::Network::UrlEventData::NumBytes "UrlEventData::NumBytes" 667 \c int64 <br/> 668 \ref BPrivate::Network::UrlEventData::TotalBytes "UrlEventData::TotalBytes" 669 \c int64 (optional) 670 </td> 671 </tr> 672 <tr> 673 <td>\ref BPrivate::Network::UrlEvent::ResponseStarted "UrlEvent::ResponseStarted"</td> 674 <td>The server has started transmitting the response.</td> 675 <td>All Protocols</td> 676 <td> 677 \ref BPrivate::Network::UrlEventData::Id "UrlEventData::Id" \c int32 <br/> 678 </td> 679 </tr> 680 <tr> 681 <td>\ref BPrivate::Network::UrlEvent::HttpRedirect "UrlEvent::HttpRedirect"</td> 682 <td> 683 The network services kit is handling a HTTP redirect. The request will be repeated 684 for a new URL. 685 </td> 686 <td>HTTP/HTTPS</td> 687 <td> 688 \ref BPrivate::Network::UrlEventData::Id "UrlEventData::Id" \c int32 <br/> 689 \ref BPrivate::Network::UrlEventData::HttpRedirectUrl 690 "UrlEventData::HttpRedirectUrl" \ref BString 691 </td> 692 </tr> 693 <tr> 694 <td>\ref BPrivate::Network::UrlEvent::HttpStatus "UrlEvent::HttpStatus"</td> 695 <td> 696 The response status is available. This means it can also be accessed through 697 \ref BPrivate::Network::BHttpResult::Status() "BHttpResult::Status()" without 698 blocking the system. 699 </td> 700 <td>HTTP/HTTPS</td> 701 <td> 702 \ref BPrivate::Network::UrlEventData::Id "UrlEventData::Id" \c int32 <br/> 703 \ref BPrivate::Network::UrlEventData::HttpStatusCode "UrlEventData::HttpStatusCode" 704 \c int16 705 </td> 706 </tr> 707 <tr> 708 <td>\ref BPrivate::Network::UrlEvent::HttpFields "UrlEvent::HttpFields"</td> 709 <td> 710 The HTTP header block has been fully received, and the HTTP fields can be accessed 711 using \ref BPrivate::Network::BHttpResult::Fields() "BHttpResult::Fields()" without 712 blocking the system. 713 </td> 714 <td>HTTP/HTTPS</td> 715 <td> 716 \ref BPrivate::Network::UrlEventData::Id "UrlEventData::Id" \c int32 717 </td> 718 </tr> 719 <tr> 720 <td>\ref BPrivate::Network::UrlEvent::DownloadProgress "UrlEvent::DownloadProgress"</td> 721 <td> 722 If there is a response body to be received, this informs you of the progress. If 723 the total size of the body is known, this will be included in the message as well. 724 </td> 725 <td>All protocols that use network connections.</td> 726 <td> 727 \ref BPrivate::Network::UrlEventData::Id "UrlEventData::Id" \c int32 <br/> 728 \ref BPrivate::Network::UrlEventData::NumBytes "UrlEventData::NumBytes" 729 \c int64 <br/> 730 \ref BPrivate::Network::UrlEventData::TotalBytes "UrlEventData::TotalBytes" 731 \c int64 (optional) 732 </td> 733 </tr> 734 <tr> 735 <td>\ref BPrivate::Network::UrlEvent::BytesWritten "UrlEvent::BytesWritten"</td> 736 <td> 737 An interim update on how many bytes have been written to the target. This message 738 is only sent when you supplied a custom target to store the body of the request in. 739 Note that the number of bytes written to the target may differ from the network 740 transfer size, due to compression in the protocol. 741 </td> 742 <td>All protocols.</td> 743 <td> 744 \ref BPrivate::Network::UrlEventData::Id "UrlEventData::Id" \c int32 <br/> 745 \ref BPrivate::Network::UrlEventData::NumBytes "UrlEventData::NumBytes" 746 \c int64 747 </td> 748 </tr> 749 <tr> 750 <td>\ref BPrivate::Network::UrlEvent::RequestCompleted "UrlEvent::RequestCompleted"</td> 751 <td> 752 The request is completed and all the data is written to the target, or there was 753 an error. 754 </td> 755 <td>All protocols.</td> 756 <td> 757 \ref BPrivate::Network::UrlEventData::Id "UrlEventData::Id" \c int32 <br/> 758 \ref BPrivate::Network::UrlEventData::Success "UrlEventData::Success" \c bool 759 </td> 760 </tr> 761 <tr> 762 <td>\ref BPrivate::Network::UrlEvent::DebugMessage "UrlEvent::DebugMessage"</td> 763 <td> 764 Additional debug information on the request. This is enabled or disabled per 765 request. See the details in the protocol description. 766 </td> 767 <td>All protocols.</td> 768 <td> 769 \ref BPrivate::Network::UrlEventData::Id "UrlEventData::Id" \c int32 <br/> 770 \ref BPrivate::Network::UrlEventData::DebugType "UrlEventData::DebugType" 771 \c uint32 <br/> 772 \ref BPrivate::Network::UrlEventData::DebugMessage "UrlEventData::DebugMessage" 773 \ref BString 774 </td> 775 </tr> 776 </table> 777*/ 778#endif 779 780 781///// Namespace Documentation ///// 782 783 784//! \brief Internal or experimental API 785namespace BPrivate { 786 787#if __cplusplus >= 201703L 788 /*! 789 \brief Experimental Network Services API 790 791 See \ref netservices for more information. 792 */ 793 namespace Network { 794 795 } 796#endif 797 798} 799
