[ Home | Alpha index | Topic index | Tutorials | Download | Feedback ]

The OS/2 API Project

PrfQueryProfileData

[ Syntax | Params | Returns | Include | Usage | Structs | Gotchas | Code | Also ]

Syntax

 bRC = PrfQueryProfileData( hini, pszAppName, pszKeyWord, pBuffer, pulBufSize );

Parameters
HINI hini (input)
Handle to profile to be searched for data. This may be one of the following:
HINI_PROFILE Search both the USER and SYSTEM profiles
HINI_USERPROFILE Search only the USER profile
HINI_SYSTEMPROFILE Search only the SYSTEM profile
a variable Search a program-defined profile. This is a HINI returned by PrfOpenProfile()

PSZ pszAppName (input)
Pointer to a null-terminated string that holds the application name to search for within the profile. This parameter may be:
NULL Specifying NULL for this parameter will return, in pBuffer, a list of all application names in the specified profile. Each name will be null-terminated, and the final name will have two null characters appended to it. If NULL is specified, then pulBufSize will not count the final null character in the return value, and pszKeyWord is ignored.
a variable This is a specific case-dependent application name to search for

PSZ pszKeyWord (input)
Pointer to a null-terminated string that holds the keyword name to search for within the application name specified. This parameter may be:
NULL Specifying NULL for this parameter will return, in pBuffer, a list of all keywords associated with the specified profile. Each name will be null-terminated, and the final name will have two null characters appended to it. If NULL is specified, then pulBufSize will not count the final null character in the return value
a variable This is a specific case-dependent application name to search for

PVOID pBuffer (output)
Pointer to buffer that PrfQueryProfileData() will fill with return data.

PULONG pulBufSize (input/output)
Pointer to a unsigned long that holds, upon calling, the size of pBuffer in bytes. If successful, PrfQueryProfileData() will put in pulBufSize the total size, in bytes, that was written to pBuffer.

Returns
BOOL bRC
This return value is always either:
TRUE success
FALSE Error occurred

If FALSE, you may use WinGetLastError() to find out what went wrong. Possible errors PrfQueryProfileData() may incur:
PMERR_INVALID_PARM 0x1303 One of the parameters to PrfQueryProfileData() was invalid
PMERR_NOT_IN_IDX 0x1304 The application name, keyword, program handle was not found
PMERR_CAN_NOT_CALL_SPOOLER 0x130D An error related to the spooler occured. (?)

Include Info

 #define INCL_WINSHELLDATA
or
#define INCL_WIN
or
#define INCL_PM
#include <os2.h>

Usage Explanation

 This function is handy for retrieving previously stored data about a program. If this API call returns FALSE, it will not touch pBuffer. Therefore, you may initialize a structure to a default configuration, call PrfQueryProfileData() and not concern yourself with whether the Appname/Keyword pair exists, as you will have a valid structure whether you've run the program before or not. See the example code for a clearer explanation of this. Even though you need to #define INCL_WIN (or one of the others) to use this API, it may be used in non-Presentation Manager programs.

Relevant Structures

Gotchas

 Both the application name and the keyword is CASE SENSITIVE. It is recommended that all your references to these strings come from a single source, such as a #define or a global variable, so as not to get tripped up on this. The returned data will be truncated to fit your buffer if it is larger than pulBufSize bytes. If you aren't sure how much space the data is going to consume, call PrfQueryProfileSize(), then allocate space for the data before calling PrfQueryProfileData(). If you specify NULL for either the application name or the keyword, and your buffer isn't large enough, the truncated data will not end with two null characters.

Sample Code

 #define INCL_WINSHELLDATA #include <os2.h> #include <stdio.h> static UCHAR szAppName[] = "MyProg"; /* Appname/Keyword declared global. */ static UCHAR szKeyWord[] = "SETTINGS"; struct progdata { UCHAR data1[10]; UINT data2; }; /* struct progdata */ int main(void) { struct progdata prg; ULONG siz = sizeof (prg); /* Initialized to default data (in case appname/keyword don't exist.) */ strcpy(prg.data1, "Default"); prg.data2 = 0; if (PrfQueryProfileData(HINI_PROFILE, szAppName, szKeyWord, &prg, &siz)) printf("PrfQueryProfileData returned TRUE.\n"); else printf("PrfQueryProfileData returned FALSE. Defaults used.\n"); printf("prg.data1 == %s\n", prg.data1); printf("prg.data2 == %d\n", prg.data2); return(0); } /* main */

See Also

 PrfOpenProfile, PrfQueryProfileSize, PrfWriteProfileData

Author

Ryan C. Gordon - warped42@ix.netcom.com

Additions

Last modified April 29/1996
Please send all errors, comments, and suggestions to: timur@vnet.ibm.com

The OS/2 API Project

PrfQueryProfileData