Topic       : TOS - The Operating System
Author      : 
Version     : tos.hyp (December 19, 2008)
Subject     : Programmieren/Atari
Nodes       : 3010
Index Size  : 93790
HCP-Version : 5
Compiled on : Atari
@charset    : atarist
@lang       : 
@default    : Title
@help       : 
@options    : +g -i -s +x +zz -t4
@width      : 70
View Ref-File8.3.9  appl_read                                                   TOS

 Name:         »Application read« - Receives a message from another 
               application.

 Opcode:       11

 Syntax:       int16_t appl_read ( int16_t ap_rid, int16_t ap_rlength, 
               void *ap_rpbuff );

 Description:  The call appl_read aids inter-process communication 
               between processes running under the AES. It will halt 
               the running application until a sufficient number of 
               bytes is available from the message pipe. The following 
               apply:

                Parameter  Meaning

                ap_rid     ID of the application from whose event 
                           buffer the data should be read
                ap_rlength Number of bytes to be read
                ap_rpbuff  Address of the buffer in which the data is 
                           to be stored

               The function waits if necessary until the demanded 
               number of bytes is actually available. In MagiC and 
               MultiTOS the function has been extended in such a way 
               that it returns immediately with a suitable message if 
               no messages are waiting at present (ap_rid: -1).

               Note: appl_read works destructively, i.e. after the 
               readout the messages are removed from the message-pipe. 
               This makes it necessary to evaluate the read message in 
               the same way as after a evnt_multi call, say.

               The presence of the extended features can be inquired 
               with appl_getinfo (opcode 6).

 Return value: WIf a 0 is returned then an error has occurred, else a 
               positive number is returned.

 Availability: All AES versions.

 Group:        Application library

 See Also:     Binding   appl_init   appl_write   evnt_mesag 
               evnt_multi