MsiRecordGetString Function

Windows Installer

MsiRecordGetString Function

The MsiRecordGetString function returns the string value of a record field.

Syntax

C++UINT MsiRecordGetString(
  __in     MSIHANDLE hRecord,
  __in     unsigned int iField,
  __out    LPTSTR szValueBuf,
  __inout  DWORD *pcchValueBuf
);

Parameters

hRecord [in]

Handle to the record.

iField [in]

Specifies the field requested.

szValueBuf [out]

Pointer to the buffer that receives the null terminated string containing the value of the record field. Do not attempt to determine the size of the buffer by passing in a null (value=0) for szValueBuf. You can get the size of the buffer by passing in an empty string (for example ""). The function then returns ERROR_MORE_DATA and pcchValueBuf contains the required buffer size in TCHARs, not including the terminating null character. On return of ERROR_SUCCESS, pcchValueBuf contains the number of TCHARs written to the buffer, not including the terminating null character.

pcchValueBuf [in, out]

Pointer to the variable that specifies the size, in TCHARs, of the buffer pointed to by the variable szValueBuf. When the function returns ERROR_SUCCESS, this variable contains the size of the data copied to szValueBuf, not including the terminating null character. If szValueBuf is not large enough, the function returns ERROR_MORE_DATA and stores the required size, not including the terminating null character, in the variable pointed to by pcchValueBuf.

Return Value

The MsiRecordGetString function returns one of the following values:

ERROR_INVALID_HANDLE

An invalid or inactive handle was supplied.

ERROR_INVALID_PARAMETER

An invalid parameter was supplied.

ERROR_MORE_DATA

The provided buffer was too small to hold the entire value.

ERROR_SUCCESS

The function succeeded.

Remarks

If ERROR_MORE_DATA is returned, the parameter which is a pointer gives the size of the buffer required to hold the string. If ERROR_SUCCESS is returned, it gives the number of characters written to the string buffer. To get the size of the buffer, pass in the address of a 1 character buffer as szValueBuf and specify the size of the buffer with pcchValueBuf as 0. This ensures that no string value returned by the function fits into the buffer. Do not attempt to determine the size of the buffer by passing in a Null (value=0).

Requirements

VersionWindows Installer 5.0 on Windows Server 2008 R2 or Windows 7. Windows Installer 4.0 or Windows Installer 4.5 on Windows Server 2008 or Windows Vista. Windows Installer on Windows Server 2003, Windows XP, and Windows 2000
HeaderMsiquery.h
LibraryMsi.lib
DLLMsi.dll
Unicode and ANSI namesMsiRecordGetStringW (Unicode) and MsiRecordGetStringA (ANSI)

See Also

Record Processing Functions
Passing Null as the Argument of Windows Installer Functions

Send comments about this topic to Microsoft

Build date: 8/13/2009

© 2009 Microsoft Corporation. All rights reserved.