(SWI &C1009)

On entry: 
R0 =  Flags
bit 0: Call using SWI OS_AddCallBack instead of directly
R1 =  Address of handler
R2 =  R12 with which to call handler
On exit:
R0 =  Allocated vector handle
Interrupts: Interrupt status is unaltered
Fast interrupts are enabled
Processor Mode:  Processor is in SVC mode
Re-entrancy: SWI is not reentrant
Use: This call installs a handler for a vector which can be arbitrarily invoked by Windows code. Some caveats apply:
  • Your handler must reside within the first 256Mb of RISC-OS memory
  • If bit 0 of the flags is not set, the handler will be called in IRQ mode with interrupts disabled just like a normal interrupt handler - hence you must take care with R14_svc and only call reentrant SWIs. You may alter R0-R3 and R12.
  • If bit 0 of the flags is set, the handler will be called next time RISC-OS is not busy. The processor mode may vary (usually SVC) and you must preserve all registers - however, you can call any SWI you like.
  • Be cautious where your handler is located - do NOT use user space memory in a multitasking environment as your code will not always exist in its specified location.
  • Because of the above point, be very sure you have deallocated the vector before your task exits. Perhaps a check on the environment exit vector code (eg; onexit())?
Related SWIs: CallWin32_VectorDeallocate (SWI &C100a)