Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
4/8/2010

This function takes an ANSI string as input, and returns an allocated string. This function does not perform ANSI to Unicode translation. It is valid only for 32-bit systems.

Syntax 

BSTR SysAllocStringByteLen(
  char FAR* 
psz, 
  unsigned int 
len 
);

Parameters

psz

[in] Null-terminated string to copy, or NULL to keep the string uninitialized.

len

[in] Number of bytes to copy from psz. A null character is placed afterwards, allocating a total of len+1 bytes.

Return Value

Returns the allocated string to indicate success, or NULL to indicate that insufficient memory exists.

Remarks

This function is provided to create strings that contain binary data. You can use this type of string only in situations where it will not be translated from ANSI to Unicode, or vice versa.

For example, do not use these strings between a 16-bit application and a 32-bit application running on a 32-bit Windows system. The OLE 16-bit to 32-bit (and 32-bit to 16-bit) interoperability layer translates the string and corrupts the binary data.

The preferred method of passing binary data is to use a SAFEARRAYof VT_UI1, which is not translated by OLE.

If pszis NULL, a string of the requested length is allocated, but not initialized.

The string designated by pszcan contain embedded null characters, and does not need to end with a NULL.

Free the returned string later with SysFreeString.

Passing invalid (and under some circumstances NULL) pointers to this function causes an unexpected termination of the application.

Requirements

Header oleauto.h
Library oleaut32.lib
Windows Embedded CE Windows CE 2.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also