libroar API overview
The API as provided by libroar and friends consists of serveral layers. While at first looking like making everything more complex are designed to make the job of the developers much more easy.
The diffrent API layers
The API consists of the following layers: the VS API, the simple API, the normal API, the low level API and the bit level. A normal developer does only get in touch with the first two levels any maybe with parts of the low level API like memory buffers if they wish. The normal API is the seldome used by developers as the simple API does normaly do the job better. The simple API adds abstraction as doing a something in a supported way automaticaly while the normal API provides multiple ways to do something and the developer must decide which way to use. The VS API adds another layer of abstraction. It's basicly designed to be as simple as possible but yet as powerful as needed by most applications. It is to be prefered if possible.
The bit level is alluded here just for completion. If a developer want to use it, in very special cases like developing a small hardware device is better directed to aroarfw.
All APIs are compatible and can freely be mixed with every other API provided.
The VS API (from Very Simple API) is designed to make it as simple as possible to communicate with a RoarAudio Server. Yet all the nice controling stuff is implemented. It is object oriented with a single object holding all stuff to communicate with the server and send or receive audio data to or from it. (It is supported that multiple VS object share the same connection to the server.)
The VIO API can currently work in two modes: It can send and receive data via application provided buffers much like classical read and write opteration of files work. And it can be used in a mode to play back a file directly. All kind of auto detection of file type is done by VS API. It even supports stuff like webradio streams out of the box!
The simple API is a abstraction of the normal API that adds abstraction mainly for cases where it must be decided how something is done. For example there are diffrent optimizations for local and remote clients.This API is normaly used by client needing more than one audio stream at the same time or controling streams owned by other clinets like change volume of such stream. Changeing volume and other control information of own streams is supported by VS API, too.
The normal API is us about how some task is to be done. This is normaly not what the application should decide and it is to be avoided to use this API.
Low level API
The low level API provides stuff like memory buffer handling, IO handling and basic protocol stuff like bit packing of messages. This can be used by the application to do some common tasks in a portable way.
VIO - Virtual I/O
VIO is a good example of the low level API: It abstracts basic IO operations like opening a file, closing it, reading and writing so this can be done in a portable way. There is a module called DSTR - Descriptive String. This is used to open files based on special filenames. DSTR can be used if a user is allowed to provide a free form filename and stuff like HTTP support is required. It will just open a file over HTTP as if it is a local file.
|Powered by Fellig.org, Vim and Freedom.|