Legacy Document

Inside Macintosh: Processes

Chapter 2 - Process Manager / Using the Process Manager

Getting Information About Other Processes

You can call the GetNextProcess, GetFrontProcess, or GetCurrentProcess functions to get the process serial number of a process. The GetCurrentProcess function returns the process serial number of the process currently executing, called the current process. This is the process whose A5 world is currently valid; this process can be in the background or foreground. The GetFrontProcess function returns the process serial number of the foreground process. For example, if your process is running in the background, you can use GetFrontProcess to determine which process is in the foreground.

The Process Manager maintains a list of all open processes. You can specify the process serial number of a process currently in the list and call GetNextProcess to get the process serial number of the next process in the list. The interpretation of the value
of a process serial number and of the order of the list of processes is internal to the Process Manager.

When specifying a particular process, use only a process serial number returned by a high-level event or a Process Manager routine, or constants defined by the Process Manager. You can use these constants to specify special processes:

CONST 
   kNoProcess        = 0;        {process doesn't exist}
   kSystemProcess    = 1;        {process belongs to OS}
   kCurrentProcess   = 2;        {the current process}

In all Process Manager routines, the constant kNoProcess refers to a process that doesn't exist, the constant kSystemProcess refers to a process belonging to the Operating System, and the constant kCurrentProcess refers to the current process.

To begin enumerating a list of processes, call the GetNextProcess function and specify the constant kNoProcess as the parameter. In response, GetNextProcess returns the process serial number of the first process in the list. You can use the returned process serial number to get the process serial number of the next process in the list. When the GetNextProcess function reaches the end of the list, it returns the constant kNoProcess and the result code procNotFound.

You can also use a process serial number to specify a target application when your application sends a high-level event. See the chapter "Event Manager" in Inside Macintosh: Macintosh Toolbox Essentials for information on how to use a process serial number when your application sends a high-level event.

You can call the GetProcessInformation function to obtain information about any process, including your own. For example, for a specified process, you can find

• the application's name as it appears in the Application menu
• the type and signature of the application
• the number of bytes in the application partition
• the number of free bytes in the application heap
• the application that launched the application

The GetProcessInformation function returns information in a process information record, which is defined by the ProcessInfoRec data type.

TYPE ProcessInfoRec =
   RECORD
      processInfoLength:   LongInt;       {length of process info record}
      processName:         StringPtr;     {name of this process}
      processNumber:       ProcessSerialNumber;
                                          {psn of this process}
      processType:         LongInt;       {file type of application file}
      processSignature:    OSType;        {signature of application file}
      processMode:         LongInt;       {'SIZE' resource flags}
      processLocation:     Ptr;           {address of partition}
      processSize:         LongInt;       {partition size}
      processFreeMem:      LongInt;       {free bytes in heap}
      processLauncher:     ProcessSerialNumber;
                                          {process that launched this one}
      processLaunchDate:   LongInt;       {time when launched}
      processActiveTime:   LongInt;       {accumulated CPU time}
      processAppSpec:      FSSpecPtr;     {location of the file}
   END;

You specify the values for three fields of the process information record: processInfoLength, processName, and processAppSpec. You must either set the processName and processAppSpec fields to NIL or set these fields to point to memory that you have allocated for them. The GetProcessInformation function returns information in all other fields of the process information record. See "Process Information Record" on page 2-16 for a complete description of the fields of this record.

Listing 2-1 shows how you can use the GetNextProcess function with the GetProcessInformation function to search the process list for a specific process.

Listing 2-1 Searching for a specific process

FUNCTION FindAProcess (signature: OSType; 
                        VAR process: ProcessSerialNumber; 
                        VAR InfoRec: ProcessInfoRec;
                        myFSSpecPtr: FSSpecPtr;
                        myName: Str31): Boolean;
BEGIN
   FindAProcess := FALSE;              {assume FALSE}
   process.highLongOfPSN := 0;
   process.lowLongOfPSN := kNoProcess; {start at the beginning}

   InfoRec.processInfoLength := sizeof(ProcessInfoRec);
   InfoRec.processName := myName;
   InfoRec.processAppSpec := myFSSpecPtr;

   WHILE (GetNextProcess(process) = noErr) DO
   BEGIN
      IF GetProcessInformation(process, InfoRec) = noErr THEN
      BEGIN
         IF (InfoRec.processType = LongInt('APPL')) AND
            (InfoRec.processSignature = signature) THEN 
         BEGIN                         {found the process}
            FindAProcess := TRUE;
            Exit(FindAProcess);
         END;
      END;
   END; {WHILE}
END;

The code in Listing 2-1 searches the process list for the application with the specified signature. For example, you might want to find a specific process so that you can send a high-level event to it.