PrfQueryProfileString

This function retrieves a string from the specified profile. This function is designed to search data written with PrfWriteProfileString.

Syntax

PrfQueryProfileString(hini, pszApp, pszKey, pszDefault, pBuffer, ulBufferMax);

Parameters

hini (HINI) - input

Initialization-file handle.

HINI_PROFILE

Both the user profile and system profile are searched

HINI_USERPROFILE

The user profile is searched

HINI_SYSTEMPROFILE

The system profile is searched

Other

Initialization-file handle returned by the PrfOpenProfile function.

pszApp (PSZ) - input

Application name

The name of the application for which the profile data is required.

The search performed on the application name is always case-dependent. Names starting with the characters "PM_" are reserved for system use.

If this parameter is NULL, this function enumerates all the application names present in the profile and returns the names as a list in the pBuffer parameter. Each application name is terminated with a NULL character and the last name is terminated with two successive NULL characters. In this instance, the ulLength parameter contains the total length of the list excluding the final NULL character.

pszKey (PSZ) - input

Key name

The name of the key for which the profile data is returned.

The search on key name is always case-dependent.

If this parameter equals NULL, and if the pszApp parameter is not equal to NULL, this function enumerates all key names associated with the named application and returns the key names (not their values) as a list in the pBuffer parameter. Each key name is terminated with a NULL character and the last name is terminated with two successive NULL characters. In this instance, the ulLength parameter contains the total length of the list excluding the final NULL character.

pszDefault (PSZ) - input

Default string.

The string that is returned in the pBuffer parameter, if the key defined by the pszKey parameter cannot be found in the profile.

If the pointer to this parameter is passed as NULL, then nothing is copied into the pszKey parameter if the key cannot be found. ulLength is returned as 0 in this case.

pBuffer (PVOID) - output

Profile string.

The text string obtained from the profile for the key defined by the pszKey parameter.

ulBufferMax (ULONG) - input

Maximum string length.

The maximum number of characters that can be put into the pBuffer parameter, in bytes. If the data from the profile is longer than this, it is truncated.

Returns

ulLength (ULONG) - returns

String length returned.

The actual number of characters (including the null termination character) returned in the pBuffer parameter, in bytes.

Errors

Possible returns from WinGetLastError:

PMERR_INVALID_PARM (0x1303)

A parameter to the function contained invalid data.

PMERR_BUFFER_TOO_SMALL (0x110B)

The supplied buffer was not large enough for the data to be returned.

PMERR_NOT_IN_IDX (0x1304)

The application name, key-name or program handle was not found.

PMERR_CAN_NOT_CALL_SPOOLER (0x130D)

An error occurred attempting to call the spooler validation routine. This error is not raised if the spooler is not installed.

PMERR_INVALID_ASCIIZ (0x130C)

The profile string is not a valid zero-terminated string.

Remarks

The call searches the profile for a key matching the name specified by the pszKey parameter under the application heading specified by the pszApp parameter. If the key is found, the corresponding string is copied. If the key does not exist, the default character string, specified by the pszDefault parameter, is copied.

If the enumerated application names exceed the available buffer space, the enumerated names are truncated, the enumerated list is not terminated with 2 bytes of zeros, and the ulLength parameter is set to the number of bytes copied into the pBuffer parameter. In this instance, the pszKey parameter is ignored.

Note: If the enumeration cannot be performed for any reason, the default character string is not copied.

This function returns the length of the list, up to, but not including, the final null. If the enumerated key names exceed the available buffer space, the enumerated names are truncated, the enumerated list is not terminated with 2 bytes of zeros, and the ulLength parameter is set to the number of bytes copied into the pBuffer parameter.

This function is case-dependent; thus the strings in the pszApp parameter and the pszKey parameter must match exactly. This avoids any code-page dependency. The application storing the data must do any case-independent matching.

The enumeration call does not distinguish between data written with the PrfWriteProfileString function and the PrfWriteProfileData function.

Sample Code

PrfQueryProfileString is issued twice to obtain the names of the default printer, the default presentation driver, and the queue associated with the printer. If any of these requests fails, the default values already defined in DEVOPENSTRUC are used.

#define INCL_WINSHELLDATA
#include <OS2.H>
char szTemp[80];
char szBuff[257];
PCH ptscan;

DEVOPENSTRUC dopPrinter = {"LPT1Q",
                          (PSZ)"IBM4201",
                           0L,
                          (PSZ)"PM_Q_STD",
                           0L, 0L, 0L, 0L, 0L};

  if (PrfQueryProfileString(HINI_PROFILE,
                           (PSZ)"PM_SPOOLER",
                           (PSZ)"PRINTER",
                            NULL,
                           (PVOID)szTemp,
                           (LONG)sizeof(szTemp)
                           )){
      szTemp[strlen(szTemp)-1] = 0;
      if (PrfQueryProfileString(HINI_PROFILE,
                               (PSZ)"PM_SPOOLER_PRINTER",
                               (PSZ)szTemp,
                                NULL,
                               (PVOID)szBuff,
                               (LONG)sizeof(szBuff)
                               )){

          ptscan = (PCH)strchr(szBuff, ';');
          ptscan++;
          ptscan = (PCH)strchr(ptscan, (INT)';');
          ptscan++;
          *(ptscan + strcspn(ptscan, ".,;")) = 0;
          dopPrinter.pszLogAddress =  ptscan;

          ptscan = (PCH)strchr(szBuff, (INT)';');
          ptscan++;
          *(ptscan + strcspn(ptscan, ".,;")) = 0;
          dopPrinter.pszDriverName = ptscan;

      }
  }