TDA Kernel DLL for native calls
tda_pipes_and_java.h
Go to the documentation of this file.
1 
5 #ifndef TDA_PIPES_AND_JAVA_H_
6 #define TDA_PIPES_AND_JAVA_H_
7 
8 #include "tdakernel.h"
9 
10 TDAEXTERN void* TDACALL TDA_LaunchPipedProcess(IN const char* program, IN const char** args);
11  // Launches an external native program.
12  // The process will be started from the directory where the TDA Kernel library resides.
13  // program - the full path to the program to execute in UTF-8 encoding;
14  // args - an array of command-line arguments NOT including the program name as the first argument;
15  // args have to be NULL-terminated, i.e, the last argument must be NULL;
16  // Returns: a libtdakernel-specific handle for the launched process (or NULL on error).
17 
18 TDAEXTERN void* TDACALL TDA_GetParentPipedProcess();
19 
20 TDAEXTERN bool TDACALL TDA_ReadProcessOutputStream(void* hProcess, void* buffer, IN unsigned int size, OUT unsigned int &read);
21 TDAEXTERN bool TDACALL TDA_WriteProcessInputStream(void* hProcess, void* buffer, IN unsigned int size, OUT unsigned int &written);
22 TDAEXTERN bool TDACALL TDA_IsPipedProcessTerminated(void* hProcess);
23 TDAEXTERN void TDACALL TDA_ReleasePipedProcess(void* hProcess, bool terminate);
24  // Closes the process handle and input/output pipe handles (if any).
25  // terminate - close the handles and terminate the process, or simply close the handles.
26 
27 TDAEXTERN const char* TDACALL TDA_GetJavaHomeAnyBits();
28  // Returns: the Java (either 32, or 64 bit --- which is found first)
29  // home directory in standard UTF-8 encoding or NULL, if Java not found.
30 TDAEXTERN const char* TDACALL TDA_GetJavaHomeSameBits();
31  // Returns: the N-bit Java home directory in standard UTF-8 encoding or NULL, if Java not found.
32  // N is 32 or 64 depending on the target platform of this DLL.
33 
34 TDAEXTERN char** TDACALL TDA_UpdateJVMOptions(IN const char** options);
35  // The "-Djava.class.path=..." and "-Djava.library.path=..." JVM options
36  // are appended by TDA-specific paths.
37  // Options is a NULL-terminated array.
38  // The result is NULL in case of error.
39  // The result (if not NULL) must be freed by calling TDA_FreeUpdatedJVMOptions().
40  // The result contains an array of options, where the last option is NULL to specify the end-of-options.
41 TDAEXTERN void TDACALL TDA_FreeUpdatedJVMOptions(IN char** options);
42 
43 TDAEXTERN void* TDACALL TDA_LaunchPipedJavaProcess(IN const char** jvmOptions, IN const char* mainClassName, IN const char** mainArgs);
44  // Launches a Java class in a separate Java VM. Implemented using TDA_GetJavaHome and TDA_LaunchProcess.
45  // The process will be started from the directory where the TDA Kernel library resides.
46  // jvmOptions - A NULL-terminated array of Java VM arguments.
47  // The "-Djava.class.path=..." and "-Djava.library.path=..." arguments
48  // are appended by TDA-specific paths.
49  // mainClassName - the full class name with the main() method to execute;
50  // mainArgs - Arguments for the main() method (NOT including the program name as the first argument).
51  // Returns: a libtdakernel-specific handle for the launched process (or NULL on error).
52 
53 TDAEXTERN void** TDACALL TDA_GetExistingJavaVMs();
54  // returns a NULL-terminated array of existing Java VMs, or NULL on error (e.g., if jvm library is not loaded yet);
55  // The result (if not NULL) must be freed by calling TDA_FreeArrayOfExistingJavaVMs().
56 TDAEXTERN void TDACALL TDA_FreeArrayOfExistingJavaVMs(IN void** array);
57 
58 TDAEXTERN bool TDACALL TDA_CreateNewJavaVM(IN const char** jvmOptions, OUT void** jvm, OUT void** jvmLibHandle);
59 TDAEXTERN void TDACALL TDA_DestroyJavaVM(IN void* jvm, IN void* jvmLibHandle);
60  // must be called from the same thread, from which TDA_CreateNewJavaVM was called;
61  // must not be called at all, if TDA_NewCreateJavaVM returned false;
62 
63 TDAEXTERN bool TDACALL TDA_LaunchJavaClass(IN void* jvm, IN const char* mainClassName, IN const char** mainArgs);
64  // Launches (in the same process and thread) the static main method of the given Java class.
65  // This is useful for native launchers.
66  // The main class name may be in the form of package1.package2.ClassName or package1/package2/ClassName
67  // TDA_CreateNewJavaVM should be called first to obtain a pointer to a JVM.
68 
69 TDAEXTERN const char* TDACALL TDA_LaunchJavaStringToStringClassMethod(IN void* jvm, IN const char* className, IN const char* methodName, IN const char* arg);
70  // Launches (in the same process and thread) the static method with the given name of the given Java class.
71  // The Java method must take exactly one String argument and must return a String value.
72  // The class name may be in the form of package1.package2.ClassName or package1/package2/ClassName
73  // TDA_CreateNewJavaVM should be called first to obtain a pointer to a JVM.
74  // The return value is NULL, if either the call was not successful, or the Java method returned null.
75 
76 TDAEXTERN void* TDACALL TDA_CreateSharedMemory(IN const char* memoryName, IN const unsigned int size);
77  // Creates/opens shared memory with the given memoryName and size.
78  // Returns a TDA-specific handle to that memory to be used in the following two functions, or NULL on error.
79  // Currently, implemented for the Windows platform only.
80 TDAEXTERN unsigned char* TDACALL TDA_GetSharedMemoryByteArray(void* sharedMemory);
81  // Returns a pointer to the byte array of the given shared memory, or NULL on error.
82  // Currently, implemented for the Windows platform only.
83 TDAEXTERN void TDACALL TDA_CloseSharedMemory(void* sharedMemory);
84  // Closes the given shared memory.
85 
86 TDAEXTERN void TDACALL TDA_Sleep(IN const unsigned int ms);
87  // Sleeps at least ms milliseconds. If ms==0, gives the remaining time of the current context switch to other threads/processes.
88 
89 #endif /* TDA_PIPES_AND_JAVA_H_ */
90 
TDAEXTERN bool TDACALL TDA_CreateNewJavaVM(IN const char **jvmOptions, OUT void **jvm, OUT void **jvmLibHandle)
TDAEXTERN const char *TDACALL TDA_GetJavaHomeSameBits()
TDAEXTERN void TDACALL TDA_CloseSharedMemory(void *sharedMemory)
TDAEXTERN char **TDACALL TDA_UpdateJVMOptions(IN const char **options)
TDAEXTERN void *TDACALL TDA_CreateSharedMemory(IN const char *memoryName, IN const unsigned int size)
TDAEXTERN void TDACALL TDA_Sleep(IN const unsigned int ms)
TDAEXTERN void TDACALL TDA_DestroyJavaVM(IN void *jvm, IN void *jvmLibHandle)
TDAEXTERN bool TDACALL TDA_ReadProcessOutputStream(void *hProcess, void *buffer, IN unsigned int size, OUT unsigned int &read)
TDAEXTERN const char *TDACALL TDA_LaunchJavaStringToStringClassMethod(IN void *jvm, IN const char *className, IN const char *methodName, IN const char *arg)
TDAEXTERN void TDACALL TDA_ReleasePipedProcess(void *hProcess, bool terminate)
TDAEXTERN void *TDACALL TDA_LaunchPipedProcess(IN const char *program, IN const char **args)
TDAEXTERN const char *TDACALL TDA_GetJavaHomeAnyBits()
TDAEXTERN unsigned char *TDACALL TDA_GetSharedMemoryByteArray(void *sharedMemory)
TDAEXTERN void *TDACALL TDA_GetParentPipedProcess()
TDAEXTERN void **TDACALL TDA_GetExistingJavaVMs()
TDAEXTERN void *TDACALL TDA_LaunchPipedJavaProcess(IN const char **jvmOptions, IN const char *mainClassName, IN const char **mainArgs)
TDAEXTERN bool TDACALL TDA_IsPipedProcessTerminated(void *hProcess)
TDAEXTERN bool TDACALL TDA_LaunchJavaClass(IN void *jvm, IN const char *mainClassName, IN const char **mainArgs)
TDAEXTERN void TDACALL TDA_FreeUpdatedJVMOptions(IN char **options)
TDAEXTERN bool TDACALL TDA_WriteProcessInputStream(void *hProcess, void *buffer, IN unsigned int size, OUT unsigned int &written)
TDAEXTERN void TDACALL TDA_FreeArrayOfExistingJavaVMs(IN void **array)