gecko-dev/include/xpgetstr.h

104 lines
4.0 KiB
C

/* -*- Mode: C; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*-
*
* The contents of this file are subject to the Netscape Public
* License Version 1.1 (the "License"); you may not use this file
* except in compliance with the License. You may obtain a copy of
* the License at http://www.mozilla.org/NPL/
*
* Software distributed under the License is distributed on an "AS
* IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
* implied. See the License for the specific language governing
* rights and limitations under the License.
*
* The Original Code is mozilla.org code.
*
* The Initial Developer of the Original Code is Netscape
* Communications Corporation. Portions created by Netscape are
* Copyright (C) 1998 Netscape Communications Corporation. All
* Rights Reserved.
*
* Contributor(s):
*/
#ifndef _XPGETSTR_H_
#define _XPGETSTR_H_
#include "prtypes.h"
XP_BEGIN_PROTOS
/**@name Platform Independent String Resources */
/*@{*/
/**
* Get a cross platform string resource by ID.
*
* This function makes localization easier for cross platform strings.
* The cross platfrom string resources are defined in allxpstr.h.
* You should use XP_GetString when:
* <OL>
* <LI>Any human readable string that not in front-end
* <LI>With the exception of HTML strings (use XP_GetStringForHTML)
* <LI>The translator/localizer will then translate the string defined
* in allxpstr.h and show the translated version to user.
* </OL>
* The caller should make a copy of the returned string if it needs to use
* it for a while. The same memory buffer will be used to store
* another string the next time this function is called. The caller
* does not need to free the memory of the returned string.
* @param id Specifies the string resource ID
* @return Localized (translated) string
* @see XP_GetStringForHTML
* @see INTL_ResourceCharSet
*/
PUBLIC char *XP_GetString(int id);
PUBLIC char *XP_CopyStringInUTF8(int id);
PUBLIC char *XP_CopyString(int id);
/**
* Get a cross platform HTML string resource by ID.
*
* This function makes localization easier for cross platform strings used
* for generating HTML. The cross platfrom string resources are defined in
* allxpstr.h. You should use XP_GetStringForHTML when:
* <OL>
* <LI>Human readable string not defined in front-end
* <LI>The code generates HTML page and will go into HTML window
* <LI>Only use this when the message will be generated into HTML.
* <LI>Only use this if you can access to the winCharSetID.
* <LI>This is needed because half of the text is generated from resource
* (in resource charset) and half of the text is coming from the net
* (in winCharSetID charset). When we meet this kind of mixing charset
* condition. We use this function instead of XP_GetString().
* </OL>
*
* The code checks the current CharSetID in the resource and the
* CharSetID of the data from the net. If they are equal, it returns the
* string defined in the resource, otherwise, it will return the English
* version. So a French client can display French if the data from the
* net is in the CharSetID of French and it will use half English and half
* Japanese if the French client receives Japanese data from the net.
*
* The caller should make a copy of the returned string if it needs to use
* it for a while. The same memory buffer will be used to store
* another string the next time this function get called. The caller
* does not need to free the memory of the returned string.
*
* @param id Specifies the string resource ID
* @param winCharSetID Specifies the winCharSetID of the HTML
* @param english Specifies the English string
* @return Localized (translated) string if the winCharSetID
* matches the CharSetID of the resource. Otherwise it
* returns the English message or the English string
* @see XP_GetStringForHTML
* @see INTL_ResourceCharSet
*/
PUBLIC char *XP_GetStringForHTML(
int id,
int16 winCharSetID,
char* english
);
/*@}*/
XP_END_PROTOS
#endif