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 PrfQueryDefinition(hini, hprog, pprogde, cbBuf)
HINI hini;               /* initialization-file handle             */
HPROGRAM hprog;          /* program handle                         */
PPROGDETAILS pprogde;    /* address of structure for program info. */
ULONG cbBuf;             /* length of buffer for program info.     */
 
The PrfQueryDefinition function retrieves information about a program or
program group.
 
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.
 
hprog      Identifies the program or group for which information is to be
           retrieved.
 
pprogde    Points to the buffer that receives the program or group
           information. This buffer is formatted as a PROGDETAILS structure,
           followed by various strings pointed to by the fields within the
           PROGDETAILS structure. This buffer must be large enough for both
           the structure and all strings returned by this function.
 
cbBuf      Specifies the size (in bytes) of the buffer pointed to by the
           pprogde parameter. If this parameter is zero, only the length of
           the data is returned and the PROGDETAILS structure is not filled
           in.
 
Return Value
 
The return value is the number of bytes copied to the buffer pointed to by
the pprogde parameter if the function is successful or zero if an error
occurs. If the cbBuf parameter is zero, the return value is the size (in
bytes) of the required buffer pointed to by the pprogde parameter.
 
Errors
 
Use the WinGetLastError function to retrieve the error value, which may be
one of the following:
 
     PMERR_BUFFER_TOO_SMALL
     PMERR_INVALID_PARM
     PMERR_INVALID_PIB
     PMERR_INVALID_PROGRAM_HANDLE
     PMERR_INVALID_GROUP_HANDLE
     PMERR_MEMORY_ALLOCATION_ERR
     PMERR_MEMORY_DEALLOCATION_ERR
     PMERR_NOT_CURRENT_PL_VERSION
     PMERR_NOT_IN_IDX
 
Comments
 
If the hprog parameter is a group handle, only the progt and pszTitle fields
in the PROGDETAILS structure pointed to by pprogde are filled in.
 
The PrfQueryDefinition function replaces the WinQueryDefintion function used
in MS OS/2, version 1.1.
 
Example
 
This example calls PrfQueryDefinition to determine the size of the buffer
needed to retrieve all of the information. It then calls DosAllocSeg to
allocate the memory and calls PrfQueryDefinition again to retrieve all of
the program information.
 
SEL sel;
ULONG cb;
PPROGDETAILS pprogde;
 
/* First find the size of the buffer needed. */
 
cb = PrfQueryDefinition(HINI_USERPROFILE, hprog, NULL, 0L);
DosAllocSeg(cb, &sel, SEG_NONSHARED);
pprogde = MAKEP(sel, 0);
cb = PrfQueryDefinition(HINI_USERPROFILE, hprog, pprogde, cb);
 
See Also
 
PrfAddProgram, PrfOpenProfile, WinQueryDefinition, PROGDETAILS,
WinGetLastError
 
                                      ♦