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 PrfQueryProgramTitles(hini, hGroup, paprogti, cbBuf, pcTitles)
HINI hini;              /* initialization-file handle               */
HPROGRAM hGroup;        /* handle of group                          */
PPROGTITLE paprogti;    /* array of structures with program info.*/
ULONG cbBuf;            /* length of buffer for array of structures */
PULONG pcTitles;        /* pointer to variable for titles           */
 
The PrfQueryProgramTitles function retrieves information about programs
within a specified group in Desktop Manager.
 
Parameter  Description
────────────────────────────────────────────────────────────────────────────
 
hini       Identifies the file that contains the program information to
           retrieve. This parameter can be an initialization-file handle
           obtained by using the PrfOpenProfile function, or it can be the
           value HINI_USERPROFILE, specifying the user-profile file.
 
hGroup     Identifies the group or program for which information is to be
           returned. This handle can be SGH_ROOT to retrieve information
           about all the groups in Desktop Manager.
 
paprogti   Points to the buffer that receives an array of one or more
           PROGTITLE structures followed by the strings pointed to within
           the structures.
 
cbBuf      Specifies the total length (in bytes) of the buffer pointed to by
           the paprogti parameter.
 
pcTitles   Points to the variable that receives the count of titles.
 
Return Value
 
The return value is the size of the required buffer if the function is
successful or zero if an error occurs.
 
Errors
 
Use the WinGetLastError function to retrieve the error value, which may be
one of the following:
 
     PMERR_BUFFER_TOO_SMALL
     PMERR_INI_FILE_CORRUPT
     PMERR_INVALID_GROUP_HANDLE
     PMERR_INVALID_PARM
     PMERR_INVALID_TARGET_HANDLE
     PMERR_MEMORY_ALLOCATION_ERR
     PMERR_MEMORY_DEALLOCATION_ERR
     PMERR_NO_ENTRIES_IN_GROUP
     PMERR_NOT_CURRENT_PL_VERSION
     PMERR_NOT_IN_IDX
     PMERR_NO_PROGRAM_FOUND
 
Comments
 
Typically an application calls this function twice. The first time, the
cbBuf parameter is set to zero. The return value is used to allocate a
sufficient buffer. Then, the application calls the function again to
retrieve the program titles.
 
If a program handle is specified for the hGroup parameter, the information
for only that instance of the program is returned.
 
See Also
 
PrfAddProgram, PrfOpenProfile, WinQueryProgramTitles, PROGTITLE
 
                                      ♦