Important Notice

The pages on this site contain documentation for very old MS-DOS software, purely for historical purposes. If you're looking for up-to-date documentation, particularly for programming, you should not rely on the information found here, as it will be woefully out of date.

                                                      ◄Up► ◄Next► ◄Previous►
────────────────────────────────────────────────────────────────────────────
 
#define INCL_WINPROGRAMLIST
 
ULONG PrfQueryProgramHandle(hini, pszExeName, phpga, cb, pcHandles)
HINI hini;            /* initialization-file handle               */
PSZ pszExeName;       /* pointer to executable-file name          */
PHPROGARRAY phpga;    /* address of structure for program handles */
ULONG cb;             /* buffer size                              */
PULONG pcHandles;     /* pointer to variable for number of handles */
 
The PrfQueryProgramHandle function retrieves the program handles that match
the name of a specified executable file.
 
Parameter   Description
────────────────────────────────────────────────────────────────────────────
 
hini        Identifies the file that contains the program information to
            retrieve. This parameter can be an initialization-file handle
            obtained by using PrfOpenProfile function, or it can be the
            value HINI_USERPROFILE, specifying the user-profile file.
 
pszExeName  Points to the fully qualified path [that is, it contains a colon
            (:) in the second position and/or contains a backslash (\)] of
            the executable file.
 
phpga       Points to the HPROGARRAY structure that receives the program
            handles, one for each match found.
 
cb          Specifies the size (in bytes) of the buffer pointed to by the
            phpga parameter. The buffer must be large enough to hold all the
            program handles retrieved.
 
pcHandles   Points to the variable that receives the number of program
            handles placed in the structure pointed to by the phpga
            parameter. If this value is zero when the function returns, the
            buffer size specified by the cb parameter is insufficient to
            hold all the program handles or an error occurred.
 
Return Value
 
The return value is the size (in bytes) of the required buffer if the
function is successful. Otherwise, it is zero, indicating an error occurred
or the filename was not found.
 
Errors
 
Use the WinGetLastError function to retrieve the error value, which may be
one of the following:
 
     PMERR_INVALID_INI_FILE_HANDLE
     PMERR_MEMORY_DEALLOCATION_ERR
     PMERR_MEMORY_ALLOCATION_ERR
 
Comments
 
Typically, an application calls this function twice. The first time, the cb
parameter is set to zero and the return value is used to determine how much
memory must be allocated to hold the program handles. The second call
actually retrieves the program handles.
 
See Also
 
PrfOpenProfile, HPROGARRAY
 
                                      ♦