PrfQueryProfileString
This function retrieves a string from the specified profile. This function is designed to search data written with PrfWriteProfileString.
Syntax
PrfQueryProfileString(HINI hini, PSZ pszApp, PSZ pszKey, PSZ pszDefault, PVOID pBuffer, ULONG 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.
- PSZ pszApp (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.
- PSZ pszKey (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.
- PSZ pszDefault (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.
- PVOID pBuffer (output)
- Profile string.
- The text string obtained from the profile for the key defined by the pszKey parameter.
- ULONG ulBufferMax (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
- ULONG ulLength (return)
- 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;
}
}