midputilkni.h

来自「This is a resource based on j2me embedde」· C头文件 代码 · 共 538 行 · 第 1/2 页

/*
 *
 *
 * Copyright  1990-2007 Sun Microsystems, Inc. All Rights Reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
 * 
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public License version
 * 2 only, as published by the Free Software Foundation.
 * 
 * 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 version 2 for more details (a copy is
 * included at /legal/license.txt).
 * 
 * You should have received a copy of the GNU General Public License
 * version 2 along with this work; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
 * 02110-1301 USA
 * 
 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
 * Clara, CA 95054 or visit www.sun.com if you need additional
 * information or have any questions.
 */

#ifndef _MIDP_UTIL_KNI_H_
#define _MIDP_UTIL_KNI_H_

/**
 * @file
 * @ingroup core_kni
 *
 * @brief Interface for KNI utility functions.
 *
 */


#include <kni.h>
#include <pcsl_string.h>
#include <midpString.h>

#ifdef __cplusplus
extern "C" {
#endif

/**
 * Gets the KNI field ID for an instance field of a class and checks it for
 * validity. See KNI_GetFieldID for further information.
 *
 * @param classHandle the handle to the containing object's class
 * @param name the field's name
 * @param signature the field's type
 */
jfieldID midp_get_field_id(KNIDECLARGS jclass classHandle,
                           const char* name,
                           const char* signature);


/**
 * Gets the KNI field ID for a static field of a class and checks it for
 * validity. See KNI_GetStaticFieldID for further information.
 *
 * @param classHandle the handle to the containing class
 * @param name the field's name
 * @param signature the field's type
 */
jfieldID midp_get_static_field_id(KNIDECLARGS jclass classHandle,
                                  const char* name,
                                  const char* signature);

/**
 * Get a String from a field of an object and converts it to pcsl_string.
 *
 * @param obj a handle to Java object whose field will be set
 * @param classObj handle of the object's class
 * @param pszFieldName field name
 * @param fieldHandle handle where to put the resulting jstring
 * @param newValue a handle to the new Java value of the field
 * @param result pointer to the location where the result must be saved
 *
 * @return status of the operation
 */
pcsl_string_status midp_get_string_field(KNIDECLARGS jobject obj, jclass classObj,
                                  char* pszFieldName, jobject fieldHandle,
                                  pcsl_string* result);

/**
 * Set a jobject field from Java platform native functions.
 *
 * Always use KNI to set an object field instead of setting it directly
 * using SNI access, since there is more to setting a object in a field
 * than just moving a reference, there is a flag to tell the the garbage
 * collector that the field is set to an object and if this flag is not
 * set then the collector not count the field as a reference which can
 * lead to premature collection of the object the field is referencing
 * and then a crash since the field will reference will not be null, it
 * will be unchanged and invalid.
 *
 * @param obj a handle to Java platform object whose field will be set
 * @param fieldName field name
 * @param fieldSignature field signature string
 * @param newValue a handle to the new Java platform value of the field
 */
void midp_set_jobject_field(KNIDECLARGS jobject obj,
			    const char *fieldName, const char *fieldSignature,
			    jobject newValue);

/**
 * Create a new MIDP string from a KNI String object.
 * If KNI String is null, an NULL_LEN length MidpString will be returned.
 * If out of memory a OUT_OF_MEM_LEN length MidpString will be returned.
 * The caller is responsible for calling midpFreeString() after use.
 * This function should not be used directly,
 * use the midpNewString macro.
 *
 * @param jStringHandle KNI Java platform String object handle
 * @param filename provided by the midpNewString macro
 * @param line provided by the midpNewString macro
 *
 * @return a new Unicode string
 */
MidpString midpNewStringImpl(jstring jStringHandle, char* filename, int line);

/**
 * Create a new MIDP string from a KNI CharArray object.
 * The caller is responsible for calling midpFreeString() after use.
 * This function should not be used directly,
 * use the midpNewStringFromArray macro.
 *
 * @param jCharArrayHandle handle to a jchar array
 * @param length desired length of the result
 * @param filename provided by the midpNewStringFromArray macro
 * @param line provided by the midpNewStringFromArray macro
 *
 * @return a new Unicode string
 */
MidpString midpNewStringFromArrayImpl(jcharArray jCharArrayHandle, int length,
				      char* filename, int line);

/**
 * @name Deprecated wrapper macros
 * Wrapper Macros so string leaks can be traced.
 * These names are deprecated since the MidpString data type is not used
 * anymore. Instead, pcsl_string is used.
 * @{
 */
#if REPORT_LEVEL <= LOG_WARNING

/** @see midpNewStringImpl */
#  define midpNewString(x)  midpNewStringImpl((x), __FILE__, __LINE__)
/** @see midpNewStringFromArrayImpl */
#  define midpNewStringFromArray(x, y) midpNewStringFromArrayImpl((x), (y), \
					__FILE__, __LINE__)

#else

/** @see midpNewStringImpl */
#  define midpNewString(x)  midpNewStringImpl((x), NULL, 0)
/** @see midpNewStringFromArrayImpl */
#  define midpNewStringFromArray(x, y) midpNewStringFromArrayImpl((x), (y), \
					NULL, 0)

#endif
/** @} */

/**
 * Create pcsl_string from the specified Java platform String object.
 * The caller is responsible for freeing the created pcsl_string when done.
 *
 * Use pcsl_string_free to free the created object.
 *
 * @param java_str pointer to the Java platform String instance
 * @param pcsl_str address of variable to receive the pcsl_string instance
 * @return status of the operation
 */
pcsl_string_status midp_jstring_to_pcsl_string(jstring java_str,
					       pcsl_string * pcsl_str);

/**
 * Create pcsl_string from the specified KNI CharArray object.
 * The caller is responsible for freeing the created pcsl_string when done.
 *
 * @param java_arr pointer to the KNI CharArray instance
 * @param length length of the text in the CharArray
 * @param pcsl_str pointer to the pcsl_string instance
 * @return status of the operation
 */
pcsl_string_status
midp_jchar_array_to_pcsl_string(jcharArray java_arr, jint length,
                                pcsl_string * pcsl_str);

/**
 * Create Java platform String object from the specified pcsl_string.
 *
 * @param pcsl_str pointer to the pcsl_string instance
 * @param java_str pointer to the Java platform String instance
 * @return status of the operation
 */
pcsl_string_status midp_jstring_from_pcsl_string(KNIDECLARGS const pcsl_string * pcsl_str,
						 jstring java_str);

/**
 * Convert a C string to a pcsl_string string.
 *
 * @param in C string specifying the text to be copied to the out parameter
 * @param out pcsl_string to receive a copy of the text specified by the in parameter
 *
 * @return jchar string
 */
pcsl_string_status pcsl_string_from_chars(const char* in, pcsl_string* out);

/**
 * Allocates a jchar array and copies all Unicode characters
 * from the given java.lang.String object (specified by jStringHandle)
 * to the allocated array.
 * A pointer to the array is stored in pAddr.
 * The caller MUST free the allocated array with midpFree() after use.
 *
 * If the given java.lang.String is null, NULL_LEN will be returned
 * and pAddr will be set to NULL.
 * If out of memory, OUT_OF_MEM_LEN will be returned
 * and pAddr will be set to NULL.
 *
 * @param jStringHandle KNI Java platform String object handle
 * @param pAddr points to a jchar* variable receiving the address of the buffer
 *              with a new Unicode string. The caller MUST free this memory
 *              using midpFree when it's not needed anymore.
 *              Receives NULL if no memory has been allocated
 *              (error or null string).
 *
 * @return the new Unicode string length, or one of the values:
 *          NULL_LEN if the string is null
 *          OUT_OF_MEM_LEN in the case of out-of-memory error
 */
jint midp_jstring_to_address_and_length(jstring jStringHandle, jchar* * pAddr);

/**
 * Starts the GET_PARAMETER_AS_PCSL_STRING...RELEASE_PCSL_STRING_PARAMETER
 * construct that provides read-only access to one string parameter.
 * The construct may be nested to provide access to multiple parameters.
 *
 * GET_PARAMETER_AS_PCSL_STRING(index,id) reads the value of the parameter
 * specified by index, assuming it is a string, and copies the text
 * to a new pcsl_string object.
 *
 * Usage 1:
 * <pre><code>
 *       KNI_StartHandles(..);
 *       GET_PARAMETER_AS_PCSL_STRING(number,parameter_name) {
 *          some code using parameter_name
 *       } RELEASE_PCSL_STRING_PARAMETER
 *       KNI_EndHandles();
 * </code></pre>
 *
 * The braces are not necessary since the construct generates a pair
 * of its own, so the below usage is equally valid:
 *
 * Usage 2:
 * <pre><code>
 *       KNI_StartHandles(..);
 *       GET_PARAMETER_AS_PCSL_STRING(number,parameter_name)
 *          some code using parameter_name
 *       RELEASE_PCSL_STRING_PARAMETER
 *       KNI_EndHandles();
 * </code></pre>
 *
 * In other words, GET_PARAMETER_AS_PCSL_STRING...RELEASE_PCSL_STRING_PARAMETER
 * defines a block. The variable whose name is passed