1 /*---------------------------------------------------------------------------* 2 * PStackTrace.h * 3 * * 4 * Copyright 2007, 2008 Nuance Communciations, Inc. * 5 * * 6 * Licensed under the Apache License, Version 2.0 (the 'License'); * 7 * you may not use this file except in compliance with the License. * 8 * * 9 * You may obtain a copy of the License at * 10 * http://www.apache.org/licenses/LICENSE-2.0 * 11 * * 12 * Unless required by applicable law or agreed to in writing, software * 13 * distributed under the License is distributed on an 'AS IS' BASIS, * 14 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * 15 * See the License for the specific language governing permissions and * 16 * limitations under the License. * 17 * * 18 *---------------------------------------------------------------------------*/ 19 20 #ifndef __PSTACKTRACE_H 21 #define __PSTACKTRACE_H 22 23 24 25 #include "ESR_ReturnCode.h" 26 #include "PortPrefix.h" 27 28 /** 29 * @addtogroup PStackTraceModule PStackTrace API functions 30 * Manipulates process stack-trace information. 31 * 32 * @{ 33 */ 34 35 /** 36 * Maximum length of stack-trace string. 37 */ 38 #define P_MAX_STACKTRACE 4096 39 40 /** 41 * Maximum length of function name. 42 */ 43 #define P_MAX_FUNCTION_NAME 80 44 45 /** 46 * Creates a new StackTrace object. 47 * 48 * @return ESR_INVALID_STATE if 1) module is already in the middle of being initialized 49 * 2) module has already been initialized by another process 3) module fails to get the current directory 50 * 4) module cannot retrieve the name of the current executing module (DLL/EXE) 51 * 5) ESR_BUFFER_OVERFLOW if an internal buffer is too small 6) module cannot retrieve the current executing module 52 * listing 7) module cannot retrieve the symbol table 8) module cannot create a new monitor 53 */ 54 PORTABLE_API ESR_ReturnCode PStackTraceCreate(void); 55 56 /** 57 * Indicates if the PStackTrace module is initialized. 58 * 59 * @param value True if the module is initialized 60 * @return ESR_INVALID_ARGUMENT is value is null; ESR_FATAL_ERROR if locking an internal mutex fails 61 */ 62 PORTABLE_API ESR_ReturnCode PStackTraceIsInitialized(ESR_BOOL* value); 63 64 /** 65 * Returns the depth of the current stack trace (0-based). 66 * 67 * @param depth [out] The depth 68 * @return ESR_NOT_SUPPORTED if debug symbols are missing 69 */ 70 PORTABLE_API ESR_ReturnCode PStackTraceGetDepth(size_t* depth); 71 72 /** 73 * Returns the current process stack-track. 74 * 75 * @param text [out] The resulting stack-trace text 76 * @param len [in/out] Size of text argument. If the return code is ESR_BUFFER_OVERFLOW, 77 * the required length is returned in this variable. 78 * @return ESR_NOT_SUPPORTED if debug symbols are missing 79 */ 80 PORTABLE_API ESR_ReturnCode PStackTraceGetValue(LCHAR* text, size_t* len); 81 82 /** 83 * Returns the current function name. 84 * 85 * @param text [out] The resulting function text 86 * @param len [in/out] Size of text argument. If the return code is ESR_BUFFER_OVERFLOW, 87 * the required length is returned in this variable. 88 * @return ESR_NOT_SUPPORTED if debug symbols are missing 89 */ 90 PORTABLE_API ESR_ReturnCode PStackTraceGetFunctionName(LCHAR* text, size_t* len); 91 92 /** 93 * Removes the deepest level of the stack-trace. 94 * 95 * @param text [in/out] The stack-trace string. 96 * @return ESR_SUCCESS 97 */ 98 PORTABLE_API ESR_ReturnCode PStackTracePopLevel(LCHAR* text); 99 100 /** 101 * Destroys the stack trace object. 102 * 103 * @return ESR_SUCCESS 104 */ 105 PORTABLE_API ESR_ReturnCode PStackTraceDestroy(void); 106 107 /** 108 * @} 109 */ 110 111 #endif /* __PSTACKTRACE_H */ 112