PrfQueryProfileSize

This function is used to obtain the size in bytes of the value of a specified key for a requested application in the profile.

Syntax

PrfQueryProfileSize( HINI hini, PSZ pszAppName, PSZ pszKeyWord, PULONG 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().

pszAppName (PSZ) - 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.

pszKeyWord (PSZ) - 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.

pulDataSize (PULONG) - 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

Returns pass or fail status (BOOL).

bRC (BOOL) - return

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 occurred. (?)

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.

If the application name is NULL, the value is the size of the application name list.

If the keyname is NULL, the value is the size of the keyname list.

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