View source for Reggae tutorial: Accessing Reggae in applications

Reggae is operated from application with two APIs. One of them is generic object oriented BOOPSI API with its ''DoMethod()'', ''GetAttr()'', ''SetAttrs()'' etc. The second API is just a shared MorphOS library one, provided by ''multimedia.class'' and is, of course, Reggae specific. To use Reggae one must open ''multimedia.class'' as every shared library. For BOOPSI API ''intuition.library'' must be opened, which almost all programs do anyway. 

==Opening and closing multimedia.class==
The first step is to add needed includes:


<tt>#include <proto/multimedia.h><br>#include <proto/exec.h><br>#include <proto/intuition.h><br>#include <clib/alib_protos.h></tt>


The first file contains definition of multimedia.class library API. It also includes ''<classes/multimedia/multimedia.h>'', containing Reggae structures, constants, tags and macros. The rest of includes are not Reggae specific, in fact most projects include them anyway, as they define basic system services. There are also additional Reggae headers, their including depends on application and will be covered in further tutorials.

Now we are ready for Reggae initialization. All what has to be done is opening ''multimedia.class'' just like an ordinary MorphOS shared library. The only noticeable difference is that library name contains path part, as Reggae classes are not directly on library search path:


<tt>struct Library* MultimediaBase;<br><br>if (MultimediaBase = OpenLibrary("multimedia/multimedia.class", 52))<br>{<br>&nbsp;&nbsp;/* Now Reggae is ready to use until the library is closed. */<br>&nbsp;&nbsp;CloseLibrary(MultimediaBase);<br>}</tt>


As with every library, the name of the base is important, as it is implicitly used in all calls to the library API as a hidden parameter. Note also the usual error handling, ''multimedia.class'' is disk-based and also performs some disk activity at startup, then checking the library base against NULL is recommended. 52 is the current ''multimedia.class'' version. Applications should request this version, as previous ones have some important features missing. Reggae cleanup is done with classic ''CloseLibrary()'' call.

'''Note:''' Some programmers use automatic library opening and closing by linking with ''libauto''. ''multimedia.class'' can be added to the list of automatically opened libraries, but it is not added by default.

A complete [http://krashan.ppa.pl/reggae/files/tutorial_basic.c example code] shows Reggae initialization. The example opens ''multimedia.class'' and, if it succeeded, prints the version and revision of ''multimedia.class'' to the console.
==Opening and closing individual classes==
Typical Reggae usage is just calling ''MediaNewObject()'' to get a data stream recognized, demultiplexed and decoded down to [[Reggae_common_formats|common formats]] automatically. In this case Reggae opens (and later closes) all needed classes automatically. Things change, when application builds processing chain by hand, or just uses single components. Then every used class must be opened and closed explicitly. It is done in the same way as with ''multimedia.class''. Let's assume our application uses just ''http.stream'' object to download some data from the net. Before object creation class must be opened. It is typically done in application setup code:


<tt>struct Library *HttpStreamBase;<br><br>
HttpStreamBase = OpenLibrary("multimedia/http.stream", 51);</tt>


As for every disk based library, checking the base against NULL is highly recommended. The class must be unloaded after use, for example in application cleanup:


<tt>CloseLibrary(HttpStreamBase);</tt>


Reggae classes are handled just like ordinary shared libraries. Note that "multimedia/" path is added to the class name, reason for this has been explained above. When a class is not used constantly in application, it may be a good idea to open it just before it is needed and close right after it is not needed anymore. For example if ''http.stream'' is used only for automatic application updates, there is no need to keep it opened after update checking/downloading. The last remark concerns names of library bases for classes. No Reggae class '''except of ''multimedia.class''''' has library-style API. Because of this library base name is not used for anything else than opening and closing the clas. That is why, the name is not important and can be anything. In these tutorials, bases names derived from classes names are used, just for improved code readability.

==I don't like C/C++, what now?==
Reggae can be used from any programming language. It has to fulfill some minimal set of features however. The first one is ability to call functions from standard MorphOS shared libraries, ''intuition.library'' and ''exec.library'' at least. Then ability to call functions from ''multimedia.class''. Many programming languages used on MorphOS have tools for creating bindings (or stubs, or whatever it is called) to shared libraries, based on C headers and *.fd files. Creating bindings for ''multimedia.class'' should not be difficult then. Then the language must have ''DoMethod()'' call. For C/C++ this call is provided by ''libabox'', a static library. Another important feature is ability to handle tag-based functions in some sane way. Taglist can be always built by hand, but passing tags as arguments to variable args functions is convenient.