MaxSDK::Util Namespace Reference

Namespaces
	DebugHelpers
	TextFile

Classes
class	AutoPtr
	Old AutoPtr class, maintained to support backwards compatibility. More...
class	BinaryStream
	Represent an abstract binary stream of data. More...
class	BinaryStreamMemory
	Holds binary data in memory only. More...
class	Char
	Represents a single Unicode character. More...
class	CharIterator
	Iterate intelligently inside a string. More...
class	CharAccumulator
	Character accumulator. More...
class	MaxStringCast
	A MaxStringCast is used when casting a MaxString to a type. More...
class	MaxString
	Stores all the strings inside CStr and WStr. More...
class	MaxStringCastUTF8
	A Utility class for helping to convert to UTF8. More...
class	MaxStringCastCP
	A Utility class for helping to convert to a specified code page. More...
class	Noncopyable
	Noncopyable is a handy utility mix-in base class that makes any class derived from it non-copyable. More...
class	Path
	Path type - adds path-operation richness over symbol strings. More...
struct	ProcessData3dsMax
	When a 3ds Max session starts up, immediately after creating the main HWND a named file mapping object is created that contains the data associated with an instance of struct ProcessData3dsMax. More...
class	StopWatch
	A basic timer tool. More...
class	TabOutOfRangeException
	Thrown when an invalid index is passed into Tab::operator[] or Tab::Addr. More...
class	IBailOutBusyProcessManager
	An interface of bailing out the busy processing functions by pressing the 'Esc' key. More...
class	BailOutManager
	A wrapper around the underlying IBailOutProcessManager instance. More...
class	FileMutexObject
	This class creates and attempts to acquire a named Mutex based on a file name in its constructor, and releases and closes the Mutex in its destructor. More...
struct	Bitwise_hash
	Template struct Bitwise_hash. More...
class	IDlgShowingStatusForPolyObj
	A pure virtual interface for Poly Object's UI as dialog Showing Status. More...
class	Exception
	Base exception class for 3ds Max. More...
class	OutOfRangeException
	Thrown when an out of bounds index is detected. More...
class	NullDereferenceException
	Thrown when a null pointer is dereferenced. More...
class	RunTimeException
	General multi-purpose exception for runtime errors. More...
class	ScopedTrace
	A diagnostic class used for tracing. More...
struct	StaticAssert
	An assert that works at compile time. More...
struct	StaticAssert< true >
class	ITipSystem
	An interface of giving users a tip . More...

Enumerations
enum	BinaryStreamMode {   BINARYSTREAM_MODE_READ = 1 << 0 , BINARYSTREAM_MODE_WRITE = 1 << 1 , BINARYSTREAM_MODE_APPEND = 1 << 2 , BINARYSTREAM_MODE_TRUNCATE = 1 << 3 ,   BINARYSTREAM_MODE_CREATE = 1 << 4 , BINARYSTREAM_MODE_TEXT = 1 << 5 , BINARYSTREAM_MODE_BINARY = 1 << 6 , BINARYSTREAM_MODE_EXCLUSIVE = 1 << 7 ,   BINARYSTREAM_MODE_COMMIT = 1 << 8 , BINARYSTREAM_MODE_TEMPORARY = 1 << 9 , BINARYSTREAM_MODE_DELETE = 1 << 10 , BINARYSTREAM_MODE_SEQUENTIAL_SCAN = 1 << 11 ,   BINARYSTREAM_MODE_RANDOM_ACCESS = 1 << 12 }
	Enum describing file open mode options. More...
enum	MaxStringDataEncoding { MSDE_CP_UTF16 = 65012 , MSDE_CP_ASCII = 65013 , MSDE_CP_UCS4 = 65014 , MSDE_CP_MASK = 0x0fffffff }
	String encodings used in the MaxString class. More...

Functions
UtilExport MaxString	VariantToString (const PROPVARIANT *, UINT encoding=CP_ACP, USHORT flags=0)
	Convert a variant into a string. More...
UtilExport bool	VariantIsString (const PROPVARIANT *)
	Determine if a variant is already a string. More...
UtilExport bool	VariantIsStringVector (const PROPVARIANT *)
	Determine if a variant is a vector of string. More...
template<typename T >
size_t	VariantToStringVector (const PROPVARIANT *, std::vector< T > &, UINT encoding=CP_ACP)
	Convert a variant into a std::vector. More...
template UtilExport size_t	VariantToStringVector< MaxString > (const PROPVARIANT *, std::vector< MaxString > &, UINT encoding)
template UtilExport size_t	VariantToStringVector< CStr > (const PROPVARIANT *, std::vector< CStr > &, UINT encoding)
template UtilExport size_t	VariantToStringVector< WStr > (const PROPVARIANT *, std::vector< WStr > &, UINT encoding)
UtilExport bool	SetStringToVariant (PROPVARIANT *, const char *str, bool clear=true)
	Sets a string inside a variant. More...
UtilExport bool	SetStringToVariant (PROPVARIANT *, const wchar_t *str, bool clear=true)
	Sets a string inside a variant. More...
UtilExport bool	VariantAddToVector (PROPVARIANT *v, const char *, UINT encoding=CP_ACP)
	Add a string entry at the end of a variant vector. More...
UtilExport bool	VariantAddToVector (PROPVARIANT *v, const wchar_t *, UINT encoding=CP_ACP)
	Add a string entry at the end of a variant vector. More...
UtilExport bool	VariantAddToVector (PROPVARIANT *v, const PROPVARIANT *, bool give=false, UINT encoding=CP_ACP)
	Add an entry at the end of a variant vector. More...
UtilExport bool	DoesVariantContainWideChars (const PROPVARIANT *variant)
	Determine if a variant contains wide-chars. More...
UtilExport bool	VariantConvertToUTF16 (PROPVARIANT *destVar, const PROPVARIANT *sourceVar, UINT codePage=CP_ACP)
	Convert a variant to UTF16. More...
UtilExport bool	VariantConvertToMBCS (PROPVARIANT *destVar, const PROPVARIANT *sourceVar, UINT codePage=CP_ACP)
	Convert a variant to MBCS. More...
MaxString	VariantToString (const VARIANT *v, UINT encoding=CP_ACP, USHORT flags=0)
MaxString	VariantToString (const PROPVARIANT &v, UINT encoding=CP_ACP, USHORT flags=0)
MaxString	VariantToString (const VARIANT &v, UINT encoding=CP_ACP, USHORT flags=0)
bool	VariantIsStringVector (const VARIANT *v)
bool	VariantIsStringVector (const PROPVARIANT &v)
bool	VariantIsStringVector (const VARIANT &v)
size_t	VariantToStringVector (const VARIANT *v, std::vector< MaxString > &ov, UINT encoding=CP_ACP)
size_t	VariantToStringVector (const PROPVARIANT &v, std::vector< MaxString > &ov, UINT encoding=CP_ACP)
size_t	VariantToStringVector (const VARIANT &v, std::vector< MaxString > &ov, UINT encoding=CP_ACP)
HWND	FindProcessMainWindow (DWORD processId, DWORD &maxVersion)
	Utility function to get the main 3ds Max window handle for the given process handle. More...
UtilExport void	UseLanguagePackLocale (HMODULE hMyModule=reinterpret_cast< HMODULE >(&__ImageBase))
	Sets the locale for a DLL or thread to match that of the language pack being used at 3ds Max start up. More...
UtilExport WORD	GetLanguageID ()
	Returns the identifier of the language used by 3ds Max. More...
UtilExport LANGID	GetLocaleValue ()
	Returns the locale ID value that is being used by 3ds Max, as set by the language pack being used at runtime. More...
UtilExport const MCHAR *	GetLocaleValueAsHexString ()
	Returns the locale ID value that is being used by 3ds Max, as set by the language pack being used at runtime. More...
UtilExport const MCHAR *	GetLanguageTLA ()
	Returns the "three letter acronym" (TLA) of the language used by 3ds Max. More...
UtilExport const MCHAR *	GetLanguagePackDirName ()
	Returns the two-two (eg "en-US" or "ja-JP") language pack directory for the language pack in use by 3ds Max. More...
UtilExport UINT	CodePageForLanguage (LANGID)
	Returns the code page corresponding to the specified locale value. More...
UtilExport bool	CopyToClipBoard (const MCHAR *text, HWND hwnd)
	copies a string to the system wide clipboard More...
UtilExport bool	ScanDirectoryTree (const MCHAR *treeroot, const MCHAR *filename, MSTR &targetpath)
UtilExport MSTR	CaptureCallStack (int skipFirstNStackLevels=3, int maxStackLevels=-1)
UtilExport MSTR	GetVersionOfFile (const MCHAR *fileName)
	Returns the file version as a string of form "#.#.#.#" where the numbers are the major version, the update version, the Hot Fix number, and the build number. More...
UtilExport MSTR	GetMaxBuildNumber ()
	Returns the 3ds Max build number as a string of form "#.#.#.#" where the numbers are the major version, the update version, the Hot Fix number, and the build number. More...
UtilExport IBailOutBusyProcessManager *	GetBailOutManager ()
UtilExport IDlgShowingStatusForPolyObj *	GetDlgShowingStatusForPolyObj ()
UtilExport BOOL	WritePrivateProfileString (LPCMSTR pSection, LPCMSTR pKeyName, LPCMSTR pString, LPCMSTR pFileName)
	These service should replace every occurrence of the standard WIN32 implementation. More...
UtilExport BOOL	WritePrivateProfileStruct (LPCMSTR pSection, LPCMSTR pKeyName, LPVOID pStruct, UINT uSizeStruct, LPCMSTR pFileName)
	Copies data into a key in the specified section of an initialization file. More...
UtilExport BOOL	WritePrivateProfileSection (LPCMSTR pSection, LPCMSTR pString, LPCMSTR pFileName)
	Replaces the keys and values for the specified section in an initialization file. More...
UtilExport DWORD	GetPrivateProfileString (LPCMSTR pSection, LPCMSTR pKeyName, LPCMSTR pDefault, LPMSTR pReturnedString, DWORD nSize, LPCMSTR pFileName)
	Gets a string from the specified section of an initialization file. More...
UtilExport DWORD	GetPrivateProfileString (LPCMSTR pSection, LPCMSTR pKeyName, LPCMSTR pDefault, MaxSDK::Array< MCHAR > &returnedString, LPCMSTR pFileName)
	Gets a string from the specified section of an initialization file. More...
UtilExport BOOL	GetPrivateProfileStruct (LPCMSTR pSection, LPCMSTR pKeyName, LPVOID pStruct, UINT uSizeStruct, LPCMSTR pFileName)
	Retrieves the data associated with a key in the specified section of an initialization file. More...
UtilExport DWORD	GetPrivateProfileSectionNames (LPMSTR pReturnedString, DWORD nSize, LPCMSTR pFileName)
	Retrieves the names of all sections in an initialization file. More...
UtilExport DWORD	GetPrivateProfileSectionNames (MaxSDK::Array< MCHAR > &returnedString, LPCMSTR pFileName)
	Retrieves the names of all sections in an initialization file. More...
UtilExport DWORD	GetPrivateProfileSection (LPCMSTR pSection, LPMSTR pReturnedString, DWORD nSize, LPCMSTR pFileName)
	Retrieves all the keys and values for the specified section of an initialization file. More...
UtilExport DWORD	GetPrivateProfileSection (LPCMSTR pSection, MaxSDK::Array< MCHAR > &returnedString, LPCMSTR pFileName)
	Retrieves all the keys and values for the specified section of an initialization file. More...
UtilExport DWORD	GetPrivateProfileInt (LPCMSTR pSection, LPCMSTR pKeyName, INT nDefault, LPCMSTR pFileName)
	Retrieves an integer associated with a key in the specified section of an initialization file. More...
TipSystemExport ITipSystem *	GetTipSystem ()

Variables
static const wchar_t *	sProcessData3dsMaxFileMappingObjectNameRoot = L"Local\\3dsmax_process_data_"
	The root name of the named file mapping object that contains the ProcessData3dsMax data. More...
static const wchar_t *	sProcessData3dsMaxFileMappingObjectNameMutexRoot = L"Local\\3dsmax_process_data_mutex"
	The root name of the mutex for accessing the named file mapping object that contains the ProcessData3dsMax data. More...
const unsigned long	INFINITE_TIME = (unsigned long)(0xffffffff)

Enumeration Type Documentation

BinaryStreamMode

enum BinaryStreamMode

Enum describing file open mode options.

Enumerator
BINARYSTREAM_MODE_READ	Allow reading from a stream.
BINARYSTREAM_MODE_WRITE	Allow writing to a stream.
BINARYSTREAM_MODE_APPEND	When opened, a stream is positioned at the end.
BINARYSTREAM_MODE_TRUNCATE	When opened, the stream is truncated.
BINARYSTREAM_MODE_CREATE	If the underlying file doesn't exist, it will create it.
BINARYSTREAM_MODE_TEXT	Specify that the underlying data should be interpreted as text. Technically, BinaryStream doesn't do anything with that flag. It's was made to use in conjunction with TextFile::Reader and TextFile::Writer.
BINARYSTREAM_MODE_BINARY	Specify that the underlying data should be considered binary.
BINARYSTREAM_MODE_EXCLUSIVE	By default, when a file is opened, another process always have the possibility to open the same file concurrently for reading. When this flag is present, it will prevent another process to to open it.
BINARYSTREAM_MODE_COMMIT	Write operations will not go through any intermediate cache, they will go directly to disk.
BINARYSTREAM_MODE_TEMPORARY	The file is being used for temporary storage.
BINARYSTREAM_MODE_DELETE	The file is to be deleted immediately after all of its handles are closed.
BINARYSTREAM_MODE_SEQUENTIAL_SCAN	Access is intended to be sequential from beginning to end.
BINARYSTREAM_MODE_RANDOM_ACCESS	Access is intended to be random.

{
    BINARYSTREAM_MODE_READ = 1 << 0,
 
    BINARYSTREAM_MODE_WRITE = 1 << 1,
    
    BINARYSTREAM_MODE_APPEND = 1 << 2,
 
    BINARYSTREAM_MODE_TRUNCATE = 1 << 3,
 
    BINARYSTREAM_MODE_CREATE = 1 << 4,
 
    BINARYSTREAM_MODE_TEXT = 1 << 5,
 
    BINARYSTREAM_MODE_BINARY = 1 << 6,
 
    BINARYSTREAM_MODE_EXCLUSIVE = 1 << 7,
 
    BINARYSTREAM_MODE_COMMIT = 1 << 8,
 
    BINARYSTREAM_MODE_TEMPORARY = 1 << 9,
 
    BINARYSTREAM_MODE_DELETE = 1 << 10,
 
    BINARYSTREAM_MODE_SEQUENTIAL_SCAN = 1 << 11,
 
    BINARYSTREAM_MODE_RANDOM_ACCESS = 1 << 12
};

MaxStringDataEncoding

enum MaxStringDataEncoding

String encodings used in the MaxString class.

In addition to the standard Windows constants like CP_ACP, CP_UTF8, etc... The following constants can also be used as encoding.

Enumerator
MSDE_CP_UTF16	Encoding for UTF16. This is 2 - 4 bytes per character.
MSDE_CP_ASCII	Encoding for windows code pages with 1 byte per character. This encoding only recognizes characters up to 127.
MSDE_CP_UCS4	Encoding up to 4 bytes per character.
MSDE_CP_MASK	Mask for use in testing encoding.

                           {
    MSDE_CP_UTF16            = 65012, 
    MSDE_CP_ASCII            = 65013, 
    MSDE_CP_UCS4             = 65014, 
    MSDE_CP_MASK             = 0x0fffffff, 
};

Function Documentation

VariantToString() [1/4]

UtilExport MaxString MaxSDK::Util::VariantToString	(	const PROPVARIANT *	,
		UINT	encoding = CP_ACP,
		USHORT	flags = 0
	)

Convert a variant into a string.

For flags, see VariantConvertType inside MSDN for a list of possible values.

VariantIsString()

UtilExport bool MaxSDK::Util::VariantIsString

(

const PROPVARIANT *

)

Determine if a variant is already a string.

VariantIsStringVector() [1/4]

UtilExport bool MaxSDK::Util::VariantIsStringVector

(

const PROPVARIANT *

)

Determine if a variant is a vector of string.

VariantToStringVector() [1/4]

size_t MaxSDK::Util::VariantToStringVector	(	const PROPVARIANT *	,
		std::vector< T > &	,
		UINT	encoding = CP_ACP
	)

Convert a variant into a std::vector.

VariantToStringVector< MaxString >()

template UtilExport size_t MaxSDK::Util::VariantToStringVector< MaxString >	(	const PROPVARIANT *	,
		std::vector< MaxString > &	,
		UINT	encoding
	)

VariantToStringVector< CStr >()

template UtilExport size_t MaxSDK::Util::VariantToStringVector< CStr >	(	const PROPVARIANT *	,
		std::vector< CStr > &	,
		UINT	encoding
	)

VariantToStringVector< WStr >()

template UtilExport size_t MaxSDK::Util::VariantToStringVector< WStr >	(	const PROPVARIANT *	,
		std::vector< WStr > &	,
		UINT	encoding
	)

SetStringToVariant() [1/2]

UtilExport bool MaxSDK::Util::SetStringToVariant	(	PROPVARIANT *	,
		const char *	str,
		bool	clear = true
	)

Sets a string inside a variant.

Parameters

str	String. Copied inside this object.
clear	If true, will perform a VariantClear on the variant.

SetStringToVariant() [2/2]

UtilExport bool MaxSDK::Util::SetStringToVariant	(	PROPVARIANT *	,
		const wchar_t *	str,
		bool	clear = true
	)

Sets a string inside a variant.

Parameters

str	String. Copied inside this object.
clear	If true, will perform a VariantClear on the variant.

VariantAddToVector() [1/3]

UtilExport bool MaxSDK::Util::VariantAddToVector	(	PROPVARIANT *	v,
		const char *	,
		UINT	encoding = CP_ACP
	)

Add a string entry at the end of a variant vector.

Supported variant types are:

• VT_VECTOR | VT_LPSTR
• VT_VECTOR | VT_LPWSTR
• VT_VECTOR | VT_VARIANT

VariantAddToVector() [2/3]

UtilExport bool MaxSDK::Util::VariantAddToVector	(	PROPVARIANT *	v,
		const wchar_t *	,
		UINT	encoding = CP_ACP
	)

Add a string entry at the end of a variant vector.

Supported variant types are:

• VT_VECTOR | VT_LPSTR
• VT_VECTOR | VT_LPWSTR
• VT_VECTOR | VT_VARIANT

VariantAddToVector() [3/3]

UtilExport bool MaxSDK::Util::VariantAddToVector	(	PROPVARIANT *	v,
		const PROPVARIANT *	,
		bool	give = false,
		UINT	encoding = CP_ACP
	)

Add an entry at the end of a variant vector.

Supported variant types are:

• VT_VECTOR | VT_LPSTR
• VT_VECTOR | VT_LPWSTR
• VT_VECTOR | VT_VARIANT

DoesVariantContainWideChars()

UtilExport bool MaxSDK::Util::DoesVariantContainWideChars

(

const PROPVARIANT *

variant

)

Determine if a variant contains wide-chars.

VariantConvertToUTF16()

UtilExport bool MaxSDK::Util::VariantConvertToUTF16	(	PROPVARIANT *	destVar,
		const PROPVARIANT *	sourceVar,
		UINT	codePage = CP_ACP
	)

Convert a variant to UTF16.

No matter what happens, the source variant is left intact. And you have the responsability to free the destination variant.

Parameters

destVar	The destination variant.
sourceVar	The source variant.
codePage	Any data stored in "sourceVar" is considered in that codepage.

VariantConvertToMBCS()

UtilExport bool MaxSDK::Util::VariantConvertToMBCS	(	PROPVARIANT *	destVar,
		const PROPVARIANT *	sourceVar,
		UINT	codePage = CP_ACP
	)

Convert a variant to MBCS.

No matter what happens, the source variant is left intact. And you have the responsability to free the destination variant.

Parameters

destVar	The destination variant.
sourceVar	The source variant.
codePage	Any data stored in "sourceVar" is considered to be in ACP. Codepage serves as a destination codepage. All ACP data will be converted to that codepage.

VariantToString() [2/4]

MaxString MaxSDK::Util::VariantToString ( const VARIANT *  v, UINT  encoding = CP_ACP, USHORT  flags = 0  )

inline

{ return VariantToString((PROPVARIANT*)v,  encoding, flags); }

VariantToString() [3/4]

MaxString MaxSDK::Util::VariantToString ( const PROPVARIANT &  v, UINT  encoding = CP_ACP, USHORT  flags = 0  )

inline

{ return VariantToString(&v,               encoding, flags); }

VariantToString() [4/4]

MaxString MaxSDK::Util::VariantToString ( const VARIANT &  v, UINT  encoding = CP_ACP, USHORT  flags = 0  )

inline

{ return VariantToString((PROPVARIANT*)&v, encoding, flags); }

VariantIsStringVector() [2/4]

bool MaxSDK::Util::VariantIsStringVector ( const VARIANT *  v )

inline

{ return VariantIsStringVector((PROPVARIANT*)v); }

VariantIsStringVector() [3/4]

bool MaxSDK::Util::VariantIsStringVector ( const PROPVARIANT &  v )

inline

{ return VariantIsStringVector(&v); }

VariantIsStringVector() [4/4]

bool MaxSDK::Util::VariantIsStringVector ( const VARIANT &  v )

inline

{ return VariantIsStringVector((PROPVARIANT*)&v); }

VariantToStringVector() [2/4]

size_t MaxSDK::Util::VariantToStringVector ( const VARIANT *  v, std::vector< MaxString > &  ov, UINT  encoding = CP_ACP  )

inline

{ return VariantToStringVector((PROPVARIANT*)v,  ov, encoding); }

VariantToStringVector() [3/4]

size_t MaxSDK::Util::VariantToStringVector ( const PROPVARIANT &  v, std::vector< MaxString > &  ov, UINT  encoding = CP_ACP  )

inline

{ return VariantToStringVector(&v,               ov, encoding); }

VariantToStringVector() [4/4]

size_t MaxSDK::Util::VariantToStringVector ( const VARIANT &  v, std::vector< MaxString > &  ov, UINT  encoding = CP_ACP  )

inline

{ return VariantToStringVector((PROPVARIANT*)&v, ov, encoding); }

FindProcessMainWindow()

HWND MaxSDK::Util::FindProcessMainWindow ( DWORD  processId, DWORD &  maxVersion  )

inline

Utility function to get the main 3ds Max window handle for the given process handle.

Parameters

processId	[in] The 3ds Max Process id to get data for.
maxVersion	[in, out] The 3ds Max version of the process.

Returns

The main 3ds Max window handle for the given process handle if found, NULL otherwise

        {
            HWND max_hwnd = NULL;
            wchar_t pidAsString[40];
            wsprintfW(pidAsString, L"%lu", processId);
            std::wstring sharedMemName = std::wstring(sProcessData3dsMaxFileMappingObjectNameRoot) + pidAsString;
 
            HANDLE hSharedMem = OpenFileMappingW(FILE_MAP_READ, 0, sharedMemName.c_str());
            if (hSharedMem)
            {
                // The shared memory needs to be guarded by OS primitive
                std::wstring sharedMemMutexName = std::wstring(sProcessData3dsMaxFileMappingObjectNameMutexRoot) + pidAsString;
                HANDLE hBufferAccessGuard = OpenMutexW(MUTEX_ALL_ACCESS, FALSE, sharedMemMutexName.c_str());
                if (hBufferAccessGuard == NULL) {
                    hBufferAccessGuard = CreateMutexW(NULL, FALSE, sharedMemMutexName.c_str());
                }
                WaitForSingleObject(hBufferAccessGuard, INFINITE);
 
                ProcessData3dsMax* pProcessData3dsMax = (ProcessData3dsMax*)MapViewOfFile(hSharedMem, FILE_MAP_READ, 0, 0, 0);
                if (pProcessData3dsMax)
                {
                    max_hwnd = (HWND)(UINT_PTR)pProcessData3dsMax->mMaxHwnd;
                    maxVersion = pProcessData3dsMax->mMaxVersion;
                    UnmapViewOfFile(pProcessData3dsMax);
                }
                CloseHandle(hSharedMem);
                hSharedMem = NULL;
 
                ReleaseMutex(hBufferAccessGuard);
                CloseHandle(hBufferAccessGuard);
                hBufferAccessGuard = NULL;
            }
            return max_hwnd;
        }

UseLanguagePackLocale()

UtilExport void MaxSDK::Util::UseLanguagePackLocale

(

HMODULE

hMyModule = reinterpret_cast< HMODULE >(&__ImageBase)

)

Sets the locale for a DLL or thread to match that of the language pack being used at 3ds Max start up.

This method must be called as soon as possible in the start up sequence of any DLL that may use localized resources, that is, in the DllMain() call in the DLL_PROCESS_ATTACH execution block.

As for threads, this method must be called as early as possible in the routine indicated by _beginthread(), _beginthreadex(), or CreateThread()'s start address parameter.

Calling this method is required in the cases above in order that 3ds Max loads files and Win32 resources from a satellite DLL installed by a language pack that may not match the locale of the OS. Otherwise, the product might run with localized resources retrieved from different satellite DLL sets, resulting in a mix of different languages.

However, if localized resources are not handled by the binary in question, or the binary is unilingual (i.e. usually that means 'English only'), then this call is probably not required but should still be made for logging purposes. This call is meant to be used with Microsoft's MUI technology, but not exclusively.

This method complements the other locale and language retrieval functions in the MaxSDK.

Parameters

hMyModule

- The handle of the dll being loaded. This is used internally for tracking the loading of dlls for debugging purposes. This parameter should not be specified when called by DllMain() as its default argument evaluates to the dll's handle. When calling from a thread proc, a parameter value of 'nullptr' should be specified so that the call is not logged as a dll load.

GetLanguageID()

UtilExport WORD MaxSDK::Util::GetLanguageID

(

)

Returns the identifier of the language used by 3ds Max.

This method complements MaxSDK::Util::GetLanguageTLA.

The language identifier is made up of a primary language identifier and a sublanguage identifier, both of which are from a set pre-defined identifiers that are part of the Windows Platform SDK.

For more information on language identifiers see National Language Support (on MSDN)

GetLocaleValue()

UtilExport LANGID MaxSDK::Util::GetLocaleValue

(

)

Returns the locale ID value that is being used by 3ds Max, as set by the language pack being used at runtime.

It is returned as a LANGID (WORD). Ex: 409 (in hex) is what it will return for English-United States.

GetLocaleValueAsHexString()

UtilExport const MCHAR* MaxSDK::Util::GetLocaleValueAsHexString

(

)

Returns the locale ID value that is being used by 3ds Max, as set by the language pack being used at runtime.

It is returned as a string. Ex: "409" (without the quotes) is what it will return for English-United States.

GetLanguageTLA()

UtilExport const MCHAR* MaxSDK::Util::GetLanguageTLA

(

)

Returns the "three letter acronym" (TLA) of the language used by 3ds Max.

This method complements MaxSDK::Util::GetLanguageID. For more information on TLA see List of Windows XP's Three Letter Acronyms for Languages

Returns

The TLA of the language used by 3ds Max.

GetLanguagePackDirName()

UtilExport const MCHAR* MaxSDK::Util::GetLanguagePackDirName

(

)

Returns the two-two (eg "en-US" or "ja-JP") language pack directory for the language pack in use by 3ds Max.

This method complements MaxSDK::Util::GetLanguageID.

Returns

The Language Pack directory name of the language used by 3ds Max.

CodePageForLanguage()

UtilExport UINT MaxSDK::Util::CodePageForLanguage

(

LANGID

)

Returns the code page corresponding to the specified locale value.

Returns code page for GetLanguageID() if the locale value is not valid. To get the locale value for the code page use GetLocaleValue()

Returns

Code page for the given locale value

CopyToClipBoard()

UtilExport bool MaxSDK::Util::CopyToClipBoard	(	const MCHAR *	text,
		HWND	hwnd
	)

copies a string to the system wide clipboard

Parameters

text	- The string to copy
hwnd	- The Window that owns the original information to be copied

ScanDirectoryTree()

UtilExport bool MaxSDK::Util::ScanDirectoryTree	(	const MCHAR *	treeroot,
		const MCHAR *	filename,
		MSTR &	targetpath
	)

CaptureCallStack()

UtilExport MSTR MaxSDK::Util::CaptureCallStack	(	int	skipFirstNStackLevels = 3,
		int	maxStackLevels = -1
	)

GetVersionOfFile()

UtilExport MSTR MaxSDK::Util::GetVersionOfFile

(

const MCHAR *

fileName

)

Returns the file version as a string of form "#.#.#.#" where the numbers are the major version, the update version, the Hot Fix number, and the build number.

Parameters

[in]

fileName

- the file name of the file to get the version number for. The function uses the search sequence specified by the LoadLibrary function.

Returns

String containing the file version, empty if the file is not found or does not have version information

GetMaxBuildNumber()

UtilExport MSTR MaxSDK::Util::GetMaxBuildNumber

(

)

Returns the 3ds Max build number as a string of form "#.#.#.#" where the numbers are the major version, the update version, the Hot Fix number, and the build number.

This is the same string seen as the Product Version of 3dsmax.exe in File Properties and at the top of the About 3ds Max dialog.

GetBailOutManager()

UtilExport IBailOutBusyProcessManager* MaxSDK::Util::GetBailOutManager

(

)

GetDlgShowingStatusForPolyObj()

UtilExport IDlgShowingStatusForPolyObj* MaxSDK::Util::GetDlgShowingStatusForPolyObj

(

)

WritePrivateProfileString()

UtilExport BOOL MaxSDK::Util::WritePrivateProfileString	(	LPCMSTR	pSection,
		LPCMSTR	pKeyName,
		LPCMSTR	pString,
		LPCMSTR	pFileName
	)

These service should replace every occurrence of the standard WIN32 implementation.

The WIN32 implementation specifies that when the file name contains UNICODE character, the file will be created with a UNICODE BOM. This is ABSOLUTLY INCORRECT!!! In order to properly save UNICODE INI file, we need to enforce that every INI file has a BOM token. Copies a string into the specified section of an initialization file. This service will create the new INI file with a UTF-16LE and delegate to WIN32 implementation to actually write the new key value pair. If the INI file exist and is not a UNICODE file, it will be re-created as a UTF-16LE and the key|value pair will be written in the proper section. This service uses a FileMutexObject instance to ensure only one 3ds Max session is accessing the .ini at a time.

Parameters

pSection	The name of the section to which the string will be copied. If the section does not exist, it is created. The name of the section is case-independent; the string can be any combination of uppercase and lowercase letters.
pKeyName	The name of the key to be associated with a string. If the key does not exist in the specified section, it is created. If this parameter is NULL, the entire section, including all entries within the section, is deleted.
pString	A null-terminated string to be written to the file. If this parameter is NULL, the key pointed to by the pKeyName parameter is deleted.
pFileName	The name of the initialization file.

Returns

If the function successfully copies the string to the initialization file, the return value is nonzero. If the file was created using Unicode characters, the function writes Unicode characters to the file. Otherwise, the function writes ANSI characters.

WritePrivateProfileStruct()

UtilExport BOOL MaxSDK::Util::WritePrivateProfileStruct	(	LPCMSTR	pSection,
		LPCMSTR	pKeyName,
		LPVOID	pStruct,
		UINT	uSizeStruct,
		LPCMSTR	pFileName
	)

Copies data into a key in the specified section of an initialization file.

As it copies the data, the function calculates a checksum and appends it to the end of the data. This service uses a FileMutexObject instance to ensure only one 3ds Max session is accessing the .ini at a time.

Parameters

pSection	The name of the section to which the string will be copied. If the section does not exist, it is created. The name of the section is case independent, the string can be any combination of uppercase and lowercase letters.
pKeyName	The name of the key to be associated with a string. If the key does not exist in the specified section, it is created. If this parameter is NULL, the entire section, including all keys and entries within the section, is deleted.
pStruct	The data to be copied. If this parameter is NULL, the key is deleted.
uSizeStruct	The size of the buffer pointed to by the pStruct parameter, in bytes.
pFileName	The name of the initialization file.

Returns

If the function successfully copies the string to the initialization file, the return value is nonzero. If the function fails, or if it flushes the cached version of the most recently accessed initialization file, the return value is zero. To get extended error information, call GetLastError.

WritePrivateProfileSection()

UtilExport BOOL MaxSDK::Util::WritePrivateProfileSection	(	LPCMSTR	pSection,
		LPCMSTR	pString,
		LPCMSTR	pFileName
	)

Replaces the keys and values for the specified section in an initialization file.

This service uses a FileMutexObject instance to ensure only one 3ds Max session is accessing the .ini at a time.

Parameters

pSection	The name of the section in which data is written.
pString	The new key names and associated values that are to be written to the named section. This string is limited to 65,535 bytes.
pFileName	The name of the initialization file. If this parameter does not contain a full path for the file, the function searches the Windows directory for the file. If the file does not exist and pFileName does not contain a full path, the function creates the file in the Windows directory. If the file exists and was created using Unicode characters, the function writes Unicode characters to the file. Otherwise, the function creates a file using ANSI characters.

Returns

If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError.

GetPrivateProfileString() [1/2]

UtilExport DWORD MaxSDK::Util::GetPrivateProfileString	(	LPCMSTR	pSection,
		LPCMSTR	pKeyName,
		LPCMSTR	pDefault,
		LPMSTR	pReturnedString,
		DWORD	nSize,
		LPCMSTR	pFileName
	)

Gets a string from the specified section of an initialization file.

This service uses a FileMutexObject instance to ensure only one 3ds Max session is accessing the .ini at a time.

Parameters

pSection	The name of the section containing the key name. If this parameter is NULL, the GetPrivateProfileString function copies all section names in the file to the supplied buffer.
pKeyName	The name of the key whose associated string is to be retrieved. If this parameter is NULL, all key names in the section specified by the pSection parameter are copied to the buffer specified by the pReturnedString parameter.
pDefault	A default string. If the pKeyName key cannot be found in the initialization file, GetPrivateProfileString copies the default string to the pReturnedString buffer. If this parameter is NULL, the default is an empty string, "".
pReturnedString	A pointer to the buffer that receives the retrieved string.
nSize	The size of the buffer pointed to by the pReturnedString parameter, in characters.
pFileName	The name of the initialization file.

Returns

The return value is the number of characters copied to the buffer, not including the terminating null character. If neither pSection nor pKeyName is NULL and the supplied destination buffer is too small to hold the requested string, the string is truncated and followed by a null character, and the return value is equal to nSize minus one. If either pSection or pKeyName is NULL and the supplied destination buffer is too small to hold all the strings, the last string is truncated and followed by two null characters. In this case, the return value is equal to nSize minus two.

GetPrivateProfileString() [2/2]

UtilExport DWORD MaxSDK::Util::GetPrivateProfileString	(	LPCMSTR	pSection,
		LPCMSTR	pKeyName,
		LPCMSTR	pDefault,
		MaxSDK::Array< MCHAR > &	returnedString,
		LPCMSTR	pFileName
	)

Gets a string from the specified section of an initialization file.

This service uses a FileMutexObject instance to ensure only one 3ds Max session is accessing the .ini at a time.

Parameters

pSection	The name of the section containing the key name. If this parameter is NULL, the GetPrivateProfileString function copies all section names in the file to the supplied buffer.
pKeyName	The name of the key whose associated string is to be retrieved. If this parameter is NULL, all key names in the section specified by the pSection parameter are copied to the buffer specified by the pReturnedString parameter.
pDefault	A default string. If the pKeyName key cannot be found in the initialization file, GetPrivateProfileString copies the default string to the pReturnedString buffer. If this parameter is NULL, the default is an empty string, "".
returnedString	A reference to the MaxSDK::Array<MCHAR> buffer that receives the retrieved string. This service will adjust the size as necessary to hold the string.
pFileName	The name of the initialization file.

Returns

The return value is the number of characters copied to the buffer, not including the terminating null character.

GetPrivateProfileStruct()

UtilExport BOOL MaxSDK::Util::GetPrivateProfileStruct	(	LPCMSTR	pSection,
		LPCMSTR	pKeyName,
		LPVOID	pStruct,
		UINT	uSizeStruct,
		LPCMSTR	pFileName
	)

Retrieves the data associated with a key in the specified section of an initialization file.

As it retrieves the data, the function calculates a checksum and compares it with the checksum calculated by the WritePrivateProfileStruct function when the data was added to the file. This service uses a FileMutexObject instance to ensure only one 3ds Max session is accessing the .ini at a time.

Parameters

pSection	The name of the section in the initialization file.
pKeyName	The name of the key whose data is to be retrieved..
pStruct	A pointer to the buffer that receives the data associated with the file, section, and key names.
uSizeStruct	The size of the buffer pointed to by the pStruct parameter, in bytes.
pFileName	The name of the initialization file.

Returns

If the function succeeds, the return value is nonzero. If the function fails, the return value is zero.

GetPrivateProfileSectionNames() [1/2]

UtilExport DWORD MaxSDK::Util::GetPrivateProfileSectionNames	(	LPMSTR	pReturnedString,
		DWORD	nSize,
		LPCMSTR	pFileName
	)

Retrieves the names of all sections in an initialization file.

This service uses a FileMutexObject instance to ensure only one 3ds Max session is accessing the .ini at a time.

Parameters

pReturnedString	A pointer to a buffer that receives the section names associated with the named file. The buffer is filled with one or more null-terminated strings; the last string is followed by a second null character.
nSize	The size of the buffer pointed to by the pReturnedString parameter, in characters.
pFileName	The name of the initialization file.

Returns

The return value is the number of characters copied to the buffer, not including the terminating null character. If the buffer is not large enough to contain all the section names associated with the specified initialization file, the return value is equal to the size specified by nSize minus two.

GetPrivateProfileSectionNames() [2/2]

UtilExport DWORD MaxSDK::Util::GetPrivateProfileSectionNames	(	MaxSDK::Array< MCHAR > &	returnedString,
		LPCMSTR	pFileName
	)

Retrieves the names of all sections in an initialization file.

This service uses a FileMutexObject instance to ensure only one 3ds Max session is accessing the .ini at a time.

Parameters

returnedString	A reference to the MaxSDK::Array<MCHAR> buffer that receives the section names associated with the named file. The buffer is filled with one or more null-terminated strings; the last string is followed by a second null character. This service will adjust the size as necessary to hold the string.
pFileName	The name of the initialization file.

Returns

The return value is the number of characters copied to the buffer, not including the terminating null character.

GetPrivateProfileSection() [1/2]

UtilExport DWORD MaxSDK::Util::GetPrivateProfileSection	(	LPCMSTR	pSection,
		LPMSTR	pReturnedString,
		DWORD	nSize,
		LPCMSTR	pFileName
	)

Retrieves all the keys and values for the specified section of an initialization file.

This service uses a FileMutexObject instance to ensure only one 3ds Max session is accessing the .ini at a time.

Parameters

pSection	The name of the section in the initialization file.
pReturnedString	A pointer to a buffer that receives the key name and value pairs associated with the named section. The buffer is filled with one or more null-terminated strings; the last string is followed by a second null character.
nSize	The size of the buffer pointed to by the pReturnedString parameter, in characters.
pFileName	The name of the initialization file.

Returns

The return value is the number of characters copied to the buffer, not including the terminating null character. If the buffer is not large enough to contain all the key name and value pairs associated with the named section, the return value is equal to the size specified by nSize minus two.

GetPrivateProfileSection() [2/2]

UtilExport DWORD MaxSDK::Util::GetPrivateProfileSection	(	LPCMSTR	pSection,
		MaxSDK::Array< MCHAR > &	returnedString,
		LPCMSTR	pFileName
	)

Retrieves all the keys and values for the specified section of an initialization file.

This service uses a FileMutexObject instance to ensure only one 3ds Max session is accessing the .ini at a time.

Parameters

pSection	The name of the section in the initialization file.
returnedString	A reference to the MaxSDK::Array<MCHAR> buffer that receives the key name and value pairs associated with the named file. The buffer is filled with one or more null-terminated strings; the last string is followed by a second null character. This service will adjust the size as necessary to hold the string.
pFileName	The name of the initialization file.

Returns

The return value is the number of characters copied to the buffer, not including the terminating null character.

GetPrivateProfileInt()

UtilExport DWORD MaxSDK::Util::GetPrivateProfileInt	(	LPCMSTR	pSection,
		LPCMSTR	pKeyName,
		INT	nDefault,
		LPCMSTR	pFileName
	)

Retrieves an integer associated with a key in the specified section of an initialization file.

This service uses a FileMutexObject instance to ensure only one 3ds Max session is accessing the .ini at a time.

Parameters

pSection	The name of the section containing the key name.
pKeyName	The name of the key whose value is to be retrieved.
nDefault	The default value to return if the key name cannot be found in the initialization file.
pFileName	The name of the initialization file.

Returns

The return value is the integer equivalent of the string following the specified key name in the specified initialization file. If the key is not found, the return value is the specified default value.

GetTipSystem()

TipSystemExport ITipSystem* MaxSDK::Util::GetTipSystem

(

)

Variable Documentation

sProcessData3dsMaxFileMappingObjectNameRoot

const wchar_t* sProcessData3dsMaxFileMappingObjectNameRoot = L"Local\\3dsmax_process_data_"

static

The root name of the named file mapping object that contains the ProcessData3dsMax data.

The process id value is appended to this string to form the full name.

sProcessData3dsMaxFileMappingObjectNameMutexRoot

const wchar_t* sProcessData3dsMaxFileMappingObjectNameMutexRoot = L"Local\\3dsmax_process_data_mutex"

static

The root name of the mutex for accessing the named file mapping object that contains the ProcessData3dsMax data.

The process id value is appended to this string to form the full name.

INFINITE_TIME

const unsigned long INFINITE_TIME = (unsigned long)(0xffffffff)