You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
 
 

244 lines
12 KiB

/*==LICENSE==*
CyanWorlds.com Engine - MMOG client, server and tools
Copyright (C) 2011 Cyan Worlds, Inc.
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>.
You can contact Cyan Worlds, Inc. by email legal@cyan.com
or by snail mail at:
Cyan Worlds, Inc.
14617 N Newport Hwy
Mead, WA 99021
*==LICENSE==*/
/**************************************************************************
THIS CODE AND INFORMATION IS PROVIDED 'AS IS' WITHOUT WARRANTY OF
ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
PARTICULAR PURPOSE.
Copyright 1998 Microsoft Corporation. All Rights Reserved.
**************************************************************************/
/**************************************************************************
File: strblock.h
Description: Programmer's interface to manipulate a block of string
resources. It defines an API with functions to Create,
Access, Modify & Destroy a string block.
**************************************************************************/
#ifndef _STRBLOCK_H
#define _STRBLOCK_H
#include <windows.h>
// The number of strings in a block. The string resource is internally
// stored as blocks of NO_OF_STRINGS_PER_BLOCK ( = 16) strings. A block
// is the smallest granularity for manipulating a string resource.
#define NO_OF_STRINGS_PER_BLOCK 16
// Error codes for operations on a string block.
typedef enum {
STRBLOCKERR_OK, // The last operation was successful.
STRBLOCKERR_NOMEMORY, // The last operation on the block failed due to inadequate memory.
STRBLOCKERR_INVALIDINDEX, // The index passed was incorrect.
STRBLOCKERR_UPDATEFAILED, // The specified app could not be updated.
STRBLOCKERR_APPLOADFAILED, // The specified app could not be loaded.
STRBLOCKERR_RESNOTFOUND, // The specified resource could not be located.
STRBLOCKERR_LOADRESFAILED, // The specified resource could not be loaded.
STRBLOCKERR_INVALIDBLOCK, // The specified block handle is invalid.
STRBLOCKERR_STRINVALID, // The string pointer passed was invalid.
STRBLOCKERR_UPDATENOTIMPLEMENTED, // UpdateResource not implemented.
STRBLOCKERR_UNKNOWN // An unspecified error.
} STRBLOCKERR;
// Handle to a block of string. We hide the internal format we use for manipulating
// a string resource by providing access to it through a handle.
DECLARE_HANDLE(HSTRBLOCK);
// Methods to access a string block.
// Function: HSTRBLOCK WINAPI GetStringBlockA( LPCSTR strAppName, UINT nBlockID,
// WORD wLangID );
// Purpose: Get the block of string with the specified ID & language from the
// specified application (ANSI version).
// LPCSTR strAppName: The name of the application.
// UINT nBlockID: The ID of the block.
// WORD wLangID: The language identifier. You can create a language
// identifier using the macro, MAKELANGID.
// Returns: Handle to a string block if successful, NULL otherwise.
// Comments: This function creates a string block. Call DeleteStringBlock()
// when you no longer need the block.
HSTRBLOCK WINAPI GetStringBlockA( LPCSTR strAppName, UINT nBlockID, WORD wLangID );
// Function: HSTRBLOCK WINAPI GetStringBlockW( LPCWSTR strAppName, UINT nBlockID,
// WORD wLangID );
// Purpose: Get the block of string with the specified ID & language from the
// specified application (UNICODE version).
// LPCWSTR strAppName: The name of the application.
// UINT nBlockID: The ID of the block.
// WORD wLangID: The language identifier. You can create a language
// identifier using the macro, MAKELANGID.
// Returns: Handle to a string block if successful, NULL otherwise.
// Comments: This function creates a string block. Call DeleteStringBlock()
// when you no longer need the block.
HSTRBLOCK WINAPI GetStringBlockW( LPCWSTR strAppName, UINT nBlockID, WORD wLangID );
// Function: BOOL WINAPI DeleteStringBlock( HSTRBLOCK hStrBlock );
// Purpose: Delete a block of string.
// HSTRBLOCK hStrBlock: The handle to the block.
// Returns: TRUE if successful, FALSE on failure.
// Comments: Call this function when you no longer need a block. Calling this function
// frees the memory occupied by the block. Failure to delete a block
// results in memory leaks.
BOOL WINAPI DeleteStringBlock( HSTRBLOCK hStrBlock );
// Function: int WINAPI GetStringLength( HSTRBLOCK hStrBlock, UINT nIndex );
// Purpose: Get the length of a string in the block.
// HSTRBLOCK hStrBlock: The handle to the string block.
// UINT nIndex: The zero-based index of the string in the block. The index can be
// any value from 0 thru' (NO_OF_STRINGS_PER_BLOCK - 1).
// Returns: If successful, the string length in number of characters, excluding the terminating
// NULL character; -1 if the function fails.
// Comments: Call this function to get the string length before calling GetString.
int WINAPI GetStringLength( HSTRBLOCK hStrBlock, UINT nIndex );
// Function: BOOL WINAPI GetStringA( HSTRBLOCK hStrBlock, UINT nIndex, LPSTR pszStr );
// Purpose: Get the string at the specified index in the block (ANSI version).
// HSTRBLOCK hStrBlock: The handle to the string block.
// UINT nIndex: The zero-based index of the string in the block. The index can be a value
// from 0 through (NO_OF_STRINGS_PER_BLOCK - 1).
// LPSTR pszStr: The pointer to the memory to which the string requested will be copied.
// This memory should be large enough to contain the string.
// Returns: TRUE on success, FALSE otherwise.
// Comments: Before calling this function, call GetStringLength() to get the string length.
BOOL WINAPI GetStringA( HSTRBLOCK hStrBlock, UINT nIndex, LPSTR pszStr );
// Function: BOOL WINAPI GetStringW( HSTRBLOCK hStrBlock, UINT nIndex, LPWSTR pszStr );
// Purpose: Get the string at the specified index in the block (UNICODE version).
// HSTRBLOCK hStrBlock: The handle to the string block.
// UINT nIndex: The zero-based index of the string in the block. The index can be a value
// from 0 through (NO_OF_STRINGS_PER_BLOCK - 1).
// LPSTR pszStr: The pointer to the memory to which the string requested will be copied.
// This memory should be large enough to contain the string.
// Returns: TRUE on success, FALSE otherwise.
// Comments: Before calling this function, call GetStringLength() to get the string length.
BOOL WINAPI GetStringW( HSTRBLOCK hStrBlock, UINT nIndex, LPWSTR pszStr );
// Function: BOOL WINAPI SetStringA( HSTRBLOCK hStrBlock, UINT nIndex, LPCSTR pszText );
// Purpose: Change the string at the specified index in the block (ANSI version).
// HSTRBLOCK hStrBlock: The handle to the string block.
// UINT nIndex: The zero-based index of the string in the block. The index can be a value
// from 0 through (NO_OF_STRINGS_PER_BLOCK - 1).
// LPCSTR pszText: The pointer to the new string.
// Returns: TRUE on success, FALSE otherwise.
BOOL WINAPI SetStringA( HSTRBLOCK hStrBlock, UINT nIndex, LPCSTR pszText );
// Function: BOOL WINAPI SetStringW( HSTRBLOCK hStrBlock, UINT nIndex, LPCWSTR pszStr );
// Purpose: Change the string at the specified index in the block (UNICODE version).
// HSTRBLOCK hStrBlock: The handle to the string block.
// UINT nIndex: The zero-based index of the string in the block. The index can be a value
// from 0 through (NO_OF_STRINGS_PER_BLOCK - 1).
// LPCWSTR pszText: The pointer to the new string.
// Returns: TRUE on success, FALSE otherwise.
BOOL WINAPI SetStringW( HSTRBLOCK hStrBlock, UINT nIndex, LPCWSTR pszText );
// Function: int WINAPI GetFirstStringID( HSTRBLOCK hStrBlock );
// Purpose: Get the ID of the first string in the block.
// HSTRBLOCK hStrBlock: The handle to the string block.
// Returns: The ID of the first string in the block. -1 if the function fails.
int WINAPI GetFirstStringID( HSTRBLOCK hStrBlock );
// Function: int WINAPI GetBlockID( HSTRBLOCK hStrBlock );
// Purpose: Get the ID of the string block. This is the ID of the string block that was
// specified when the block was created.
// HSTRBLOCK hStrBlock: The handle to the string block.
// Returns: The block ID, if sucessful, or -1 on failure.
int WINAPI GetBlockID( HSTRBLOCK hStrBlock );
// Function: WORD WINAPI GetBlockLanguage( HSTRBLOCK hStrBlock );
// Purpose: Get the identifier of the language for the string block. This is the language ID
// specified when the block was created.
// HSTRBLOCK hStrBlock: The handle to the string block.
// Returns: The language ID of the block, if successful; 0 on failure.
// Comments: For info on language IDs, refer help of MAKELANGID.
WORD WINAPI GetBlockLanguage( HSTRBLOCK hStrBlock );
// Function: BOOL WINAPI UpdateStringBlockA( LPCSTR strAppName, HSTRBLOCK hStrBlock,
// int nBlockID, WORD wLangID );
// Purpose: Update the block of string resource in the specified application
// (ANSI version).
// LPCTSTR strAppName: The name of the application whose string resource has to be updated.
// HSTRBLOCK hStrBlock: The handle to the block that contains the new strings.
// int nBlockID: The ID of the block to update in the app. If it is -1, use the same block
// ID as that of hStrBlock.
// WORD wLangID: The identifier of the language whaose string block has to be updated. If this
// value is 0, use the same language as that of hStrBlock.
// Returns: TRUE on success, FALSE on failure.
BOOL WINAPI UpdateStringBlockA( LPCSTR strAppName, HSTRBLOCK hStrBlock, int nBlockID, WORD wLangID );
// Function: BOOL WINAPI UpdateStringBlockW( LPCWTR strAppName, HSTRBLOCK hStrBlock,
// int nBlockID, WORD wLangID );
// Purpose: Update the block of string resource in the specified application
// (UNICODE version).
// LPCTSTR strAppName: The name of the application whose string resource has to be updated.
// HSTRBLOCK hStrBlock: The handle to the block that contains the new strings.
// int nBlockID: The ID of the block to update in the app. If it is -1, use the same block
// ID as that of hStrBlock.
// WORD wLangID: The identifier of the language whaose string block has to be updated. If this
// value is 0, use the same language as that of hStrBlock.
// Returns: TRUE on success, FALSE on failure.
BOOL WINAPI UpdateStringBlockW( LPCWSTR strAppName, HSTRBLOCK hStrBlock, int nBlockID, WORD wLangID );
// Function: STRBLOCKERR WINAPI GetStringBlockError();
// Purpose: Get the error status of the last string block action.
// Returns: The error status of the last operation on the specified block.
// Comments: The error code is maintained on a per-thread basis. Multiple threads do not
// overwrite each other's last block error code.
STRBLOCKERR WINAPI GetStringBlockError();
#ifdef UNICODE
#define GetStringBlock GetStringBlockW
#define GetString GetStringW
#define SetString SetStringW
#define UpdateStringBlock UpdateStringBlockW
#else
#define GetStringBlock GetStringBlockA
#define GetString GetStringA
#define SetString SetStringA
#define UpdateStringBlock UpdateStringBlockA
#endif // UNICODE
#endif // _STRBLOCK_H