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.10  appl_search                                                TOS

 Name:         »Application search« - Search for applications in 
               system.

 Opcode:       18

 Syntax:       int16_t appl_search ( int16_t ap_smode, int8_t 
               *ap_sname, int16_t *ap_stype, int16_t *ap_sid );

 Description:  Depending on the parameters, the function appl_search 
               searches for filenames of various applications running 
               in the system. The following apply:

                Parameter Meaning

                ap_smode  Search for:
                           APP_FIRST     0      First application 
                           APP_NEXT      1      Next application 
                           APP_DESK      2      System shell 
                           APP_TASKINFO  0x100  Request task info, 
                                                XaAES bit that may be added. 

                ap_sname  Buffer that receives the name of the found 
                          application filename (at least 9 bytes 
                          including a terminating NULL-byte)
                ap_stype  Type of the process as bit-vector:
                           APP_SYSTEM       0x001  System process 
                           APP_APPLICATION  0x002  Application 
                           APP_ACCESSORY    0x004  Accessory 
                           APP_SHELL        0x008  System shell 
                           APP_HIDDEN       0x100  Task is disabled, 
                                                   XaAES only for APP_TASKINFO 
                           APP_FOCUS        0x200  Active application, 
                                                   XaAES only for APP_TASKINFO 

                ap_sid    ID of the found application

               It is possible to obtain the long name of the applica- 
               tion if one knows its application ID.

               The long name is the one that was passed by the appli- 
               cation at a menu_register call and is also displayed in 
               the menu bar.

               If one knows the application ID apid of an application, 
               then its long name will be transferred to the buffer 
               longname by a following call of appl_search:

               appl_search(-apid, &longname[0], &type, &pid)

               type here is the bit-mask of the application type also 
               returned normally, pid the MiNT-pid (not: apid) of the 
               application.

               So the first parameter to be passed is the negative 
               value of the application ID to obtain the long name of 
               this application. This name can be up to 32 characters 
               long (31 characters plus terminating NULL-byte), so one 
               should reserve a correspondingly sized buffer for 
               longname.

               APP_TASKINFO automatically returns the long name of an 
               application and is available only under XaAES.

               With this routine one cannot find threads.

               Geneva has three extra modes:

                  . X_APS_CHEXIT (-1)
                    Retrieves the name, ID, and type of the last 
                    application to exit. This makes it possible for a 
                    program which receives a CH_EXIT notice to 
                    determine the name of the program which exited. 
                    Note that this information is not buffered; this 
                    means that if one process terminates and its 
                    parent does not make the appl_search call before a 
                    second one does, the information will no longer 
                    reflect the first process which terminated.

                  . X_APS_CHILD0 (0x7100)
                    Retrieve the data concerning the child of the 
                    current application which has the lowest 
                    application ID. (This is not necessarily the first 
                    child application the parent ran.)

                  . X_APS_CHILD (0x7101)
                    Retrieve the data for each additional child of the 
                    current application.

 Return value: The function returns the value 1 if no error has 
               arisen, or the value 0 if no further applications are 
               present.

 Availability: The presence of this function can be ascertained with 
               appl_getinfo (opcode 4). Ascertaining of the long name 
               and task information can be recognized by appl_getinfo 
               (opcode 64).

 Group:        Application library

 See Also:     Binding   appl_find   Broadcasting