SetupGetLineText
[New
- Windows NT]
The SetupGetLineText
function returns the contents of a line in an INF file in a compact form. The
line to retrieve can be specified by an INFCONTEXT structure returned from a SetupFindLineXXX
function, or by explicitly passing in the INF handle, section, and key of
the desired line.
BOOL SetupGetLineText(
|
PINFCONTEXT Context, |
// optional,
context of an INF file |
|
HINF InfHandle, |
// optional,
handle to an INF file |
|
PCTSTR Section, |
// optional,
section in an INF file |
|
PCTSTR Key, |
// optional, key
to look for |
|
PTSTR ReturnBuffer, |
// optional,
receives the line text |
|
DWORD ReturnBufferSize, |
// size of the
supplied buffer |
|
PDWORD RequiredSize |
// optional, buffer size needed |
|
); |
|
Parameters
Context
Supplies
context for a line in an INF file whose text is to be retrieved. If Context
is NULL, InfHandle, Section, and Key must be specified.
InfHandle
Handle of the
INF file to query. This parameter is used only if Context is NULL.
Section
Pointer to a
null-terminated string that specifies the section containing the key name of
the line whose text is to be retrieved. This parameter is used only if Context
is NULL.
Key
Pointer to a
null-terminated string containing the key name whose associated string is to be
retrieved. This parameter is used only if Context is NULL.
ReturnBuffer
If not NULL,
points to a caller-supplied buffer in which this function returns the contents
of the line.
ReturnBufferSize
Specifies the
size of the buffer pointed to by the ReturnBuffer parameter.
RequiredSize
If not NULL,
points to a caller-supplied variable in which this function returns the
required size for the buffer pointed to by the ReturnBuffer parameter.
If ReturnBuffer is specified and the size needed is larger than the
value specified in the ReturnBufferSize parameter, the function fails
and does not store data in the buffer.
Return Values
If the
function succeeds, the return value is TRUE.
If the
function fails, the return value is FALSE. To get extended error information, call
GetLastError.
Remarks
For the
Unicode version of this function, the buffer sizes ReturnBufferSize and RequiredSize
are specified in number of characters. This number includes the null
terminator. For the ANSI version of this function, the sizes are specified in
number of bytes.
If this
function is called with a ReturnBuffer of NULL and a ReturnBufferSize of
zero, the function puts the buffer size needed to hold the specified data into
the variable pointed to by RequiredSize. If the function succeeds in
this, the return value is TRUE. Otherwise, the return value is FALSE and
extended error information can be obtained by calling GetLastError.
Thus, you can
call the function once to get the required buffer size, allocate the necessary
memory, and then call the function a second time to retrieve the data. Using
this technique, you can avoid errors due to an insufficient buffer size.
This function
returns the contents of a line in a compact format. All extraneous white space
is removed and multi-line values are converted into a single contiguous string.
For example, this line:
HKLM, , PointerClass0, 1 \
; This is a comment
01, 02, 03
would be
returned as:
HKLM,,PointerClass0,1,01,02,03
See Also