
Use of ARLib without RiscOS_Lib

ARLib has been written with the assumption that the main program uses RiscOS_Lib. It is 
still possible to use it if this is not the case, however veneer functions will have to be written 
to convert the calls to the Risc_OSlib functions into calls to whatever run-time library is 
actually in use.

Below is a full list of the function use and dependencies of the files within ARLib. 
Knowledge of what the Risc_OSLib functions do is assumed.

Common function use

Throughout most of the files several functions are used.

char *msgs_lookup(const char *msg_and_tag);

This provides for internationalisation of the library. All the English messages 
are embedded in the library as defaults. The Messages file contains the 
complete list if translations are needed.

void werr(int fatal, const char *msg, ...);

This is the usual warning error message. It is never called with a fatal error. But 
see also arerr.c below.

extern os_error *file_open(int opts, const char *filename, filehandle 
*handle);
extern os_error *file_close(filehandle handle);
extern os_error *file_bget(filehandle f, int *byte_read);
extern os_error *file_readfrom(filehandle f, void *data, size_t nbytes, 
unsigned int fileptr);
extern os_error *file_load(const char *filename, void *addr);
extern os_error *file_readlinebuffer(filehandle f, char *buffer, int 
bufsize);
extern os_error *file_setpos(filehandle f, int pos);
extern os_error *file_getpos(filehandle f, int *pos);

These calls are veneers for filing system operations, and are defined in 
utilasm.s. Several of the files use them.
armovie.c

This contains the main user interface to the library and contains all the functions that you 
would normally need to access. 

It calls :-

void alarm_removeall(void *handle);
void alarm_set(int at, alarm_handler proc, void *handle);
int alarm_timedifference(int t1, int t2);
int alarm_timenow(void);

The alarm() functions are used to schedule the loading of the sound chunks.

arsndcode.c

This file contains the low level interface to and management of the SoundCode resources. It 
is the only file that accesses the device() functions.

It calls:-

int alarm_timedifference(int t1, int t2);
int alarm_timenow(void);

The alarm() functions are used to set up the end of the timing routine.


Some functions are used from the support modules rather than the main code modules and 
so if they are replaced in toto then these functions are unnecessary.

arlibmain.c

This file exists only to initialise the library and set up an event processor to handle mode 
changes. It is probably most easily rewritten or incorporated into the main program.

It calls :-

void win_add_unknown_event_processor(win_unknown_event_processor, void 
*handle);

Watches for Message_ModeChange and if the mode has really changed calls 
armovie_modechange().

os_error *os_byte(int r0, int *r1, int *r2);

	Read the current mode so it knows when it actually changes.

device.c

This file provides a generic interface to the device claim protocol. See its header file 
device.h if you do want to replace it totally.

The functions from Risc_OSLib it uses are :-

char *wimpt_programname(void);

Gets the task name to use as information in the device claim message.

void event_process(void);

Called in a loop whilst waiting for a Message_DeviceInUse from another task 
or for the wimp to acknowledge the Message_DeviceClaim as unclaimed.

void win_add_unknown_event_processor(win_unknown_event_processor,
                                    void *handle);
void win_remove_unknown_event_processor(win_unknown_event_processor,
                                     void *handle);

Add or remove the message handler looking for the device claim protocol 
messages.




arerr.c

This file contains definitions of the following error routines.

int oom_err(const char *msg, int size);
os_error *os__err(os_error *e);
os_error *no__err(os_error *e);

They are used throughout the library and arerr maps them onto calls to werr and 
wimpt_complain.

Memory management veneers

Three files are provided that wrap veneers around existing memory allocation routines. This 
then gives them common function prototypes and so they can be replaced by means of the 
various armovie_registerxxxmemfns() calls. This allows the choice of whether to use 
flex memory or not for example.

The only proviso with writing extra veneers is that they must be 'safe' routines. ie they must 
treat null pointers in the same way that malloc and free do. They will always be passed non-
zero anchors. It is the contents of the anchor that must be treated carefully.

m_alloc.c

This file contains veneers to the OS_Module calls to allocate memory from the RMA. It just 
uses the usual swi and error functions.

c_alloc.c

This file contains veneers to the SharedCLibrary functions malloc and free to allocate 
memory from the C heap. It just uses the usual error functions.

f_alloc.c

This file contains veneers to flex_alloc, flex_extend and flex_free. It uses no outside calls 
itself but the flex module uses :-

os_error *wimp_slotsize(int *currentslot /*inout*/,
                        int *nextslot /*inout*/,
                        int *freepool /*out*/);

extern void wimpt_noerr(os_error *e);

d_alloc.c

This creates a dynamic area of the given size (RISC OS 3.50 only). It uses only the standard 
swi and error functions.



Miscellaneous functions

utils.c
utilasm.s

These files contains a few miscellaneous functions used throughout the library which may 
already have equivalents in your own code or libraries so could conceivably be replaced.

