PrfQueryProfileSize

PrfQueryProfileSize

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: {| border="1"

| 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.

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