SysAllocStringByteLen

This function takes an ANSI string as input, and returns a BSTR that contains an ANSI string. This function does not perform any ANSI to Unicode translation.

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.

  Allocates a new string of len bytes, copies len bytes from the passed string into it, and then appends a null character. Valid only for 32-bit systems.

Return Values

Returns a pointer to a copy of the string indicates success. NULL indicates that insufficient memory exists.

Remarks

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

For example, do not use these BSTRs between a 16-bit 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 will translate the BSTR and corrupt the binary data. The preferred method of passing binary data is to use a SAFEARRAY of VT_UI1, which will not be translated by OLE.

If psz is NULL, a string of the requested length is allocated, but not initialized. The string psz can 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

OS Versions: Windows CE 2.0 and later.
Header: Oleauto.h.
Link Library: Oleaut32.lib.

See Also

BSTR | SAFEARRAY | SysFreeString

Last updated on Wednesday, April 13, 2005

© 2005 Microsoft Corporation. All rights reserved.