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

The OS/2 API Project

PrfQueryProfileSize

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

Syntax

bRC = PrfQueryProfileSize( hini, pszAppName, pszKeyWord, pulDataSize );

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 pulDataSize, the number of bytes need to store an enumerated list of all the application names in this profile. pszKeyWord will be ignored. See PrfWriteProfileString() for more information on retrieving this list.
a variable This is a specific case-sensitive 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 pulDataSize, the number of bytes need to store an enumerated list of all the keywords in this profile. If NULL is specified for pszAppName, this parameter is ignored. See PrfWriteProfileString() for more information on retrieving this list.
a variable This is a specific case-sensitive keyword to search for.

PULONG pulDataSize (output)
Pointer to an unsigned long that will store, upon return, the number of bytes that will be required to store the data associated with the application/keyword pair in the specified profile. If either pszAppName or pszKeyWord is NULL, then this will have the number of bytes needed to store an enumerated list.

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

Use this function if you aren't sure how much space the data in a profile will take up, and then allocate memory based on PrfQueryProfileSize()'s return values.

Relevant Structures

Gotchas

Both the application name and the keyword are 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.

Sample Code

#define INCL_WINSHELLDATA #include <os2.h> #include <stdio.h> #include <stdlib.h> static UCHAR szAppName[] = "MyProg"; /* Appname/Keyword declared global. */ static UCHAR szKeyWord[] = "CopyrightMsg"; int main(void) { PSZ pszMyString; ULONG ulSiz; if (!PrfQueryProfileSize(HINI_USERPROFILE, szAppName, szKeyWord, &ulSiz)) { printf("PrfQueryProfileData failed!\n"); return(1); } /* if */ pszMyString = (PSZ) malloc(ulSiz); if (pszMyString == NULL) { printf("Memory allocation error.\n"); return(2); } /* if */ PrfQueryProfileString(HINI_USERPROFILE, szAppName, szKeyWord, "DEFAULT STRING", pszMyString, ulSiz); printf("String stored in profile == \"%s\"\n", pszMyString); free((void *) pszMyString); return(0); } /* main */

See Also

PrfQueryProfileData, PrfQueryProfileString

Author

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

Additions

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

The OS/2 API Project

PrfQueryProfileSize