00001 /* 00002 COSTA: Problem solving environment for data assimilation 00003 Copyright (C) 2005 Nils van Velzen 00004 00005 This library is free software; you can redistribute it and/or 00006 modify it under the terms of the GNU Lesser General Public 00007 License as published by the Free Software Foundation; either 00008 version 2.1 of the License, or (at your option) any later version. 00009 00010 This library is distributed in the hope that it will be useful, 00011 but WITHOUT ANY WARRANTY; without even the implied warranty of 00012 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 00013 Lesser General Public License for more details. 00014 00015 You should have received a copy of the GNU Lesser General Public 00016 License along with this library; if not, write to the Free Software 00017 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 00018 */ 00019 00020 /** 00021 \file cta_handles.h 00022 \brief Description of functions for working with CTA_Handle objects that are being used to access COSTA objects. 00023 */ 00024 00025 #ifndef CTA_HANDLES_H 00026 #define CTA_HANDLES_H 00027 00028 #include "cta_datatypes.h" 00029 00030 // Constants 00031 00032 // Derived types 00033 CTAEXPORT typedef int CTA_Handle; 00034 00035 /* String instance handle - needed for GetName() */ 00036 CTAEXPORT typedef CTA_Handle CTA_String; 00037 00038 #ifdef __cplusplus 00039 extern "C" { 00040 #endif 00041 00042 // Interfaces 00043 /** \brief Create a new COSTA handle 00044 * 00045 * \param name I name associated with handle 00046 * \param datatype I data type of handle 00047 * \param data I block of data associated to handle 00048 * \param handle O receives COSTA handle 00049 * \return error status: CTA_OK 00050 */ 00051 CTAEXPORT int CTA_Handle_Create(const char *name, const CTA_Datatype datatype, 00052 void *data, CTA_Handle *handle); 00053 00054 /** \brief Free a COSTA handle 00055 * 00056 * \note The data part of the handle is NOT freed. 00057 * 00058 * \param handle IO handle that is to be freed, replaced by CTA_NULL on return. 00059 * \return error status: CTA_OK, CTA_ILLEGAL_HANDLE 00060 */ 00061 CTAEXPORT int CTA_Handle_Free(CTA_Handle *handle); 00062 00063 /** \brief Free a COSTA handle 00064 * 00065 * \note Calls datatype-specific free methods, if available. 00066 * 00067 * \param handle IO handle that must be freed, replaced by CTA_NULL on return. 00068 * \return error status: CTA_OK, CTA_ILLEGAL_HANDLE 00069 */ 00070 CTAEXPORT int CTA_Handle_Free_All(CTA_Handle *handle); 00071 00072 /** \brief Check whether a handle is valid and checks type 00073 * 00074 * \note The handle CTA_NULL is not valid. 00075 * 00076 * \param handle I COSTA handle 00077 * \param datatype I data type to compare handle with 00078 * \return error status: CTA_OK, CTA_ILLEGAL_HANDLE, CTA_INCOMPATIBLE_HANDLE 00079 * 00080 */ 00081 CTAEXPORT int CTA_Handle_Check(const CTA_Handle handle,const CTA_Datatype datatype); 00082 00083 /** \brief Get pointer to data element of handle 00084 * 00085 * \param handle I COSTA handle 00086 * \param data O receives pointer to data element 00087 * \return error status: CTA_OK, CTA_ILLEGAL_HANDLE 00088 */ 00089 CTAEXPORT int CTA_Handle_GetData(const CTA_Handle handle, void **data); 00090 00091 /** \brief Get the value the handle points to 00092 * 00093 * \param handle I COSTA handle 00094 * \param value O receives pointer to data element 00095 * \param datatype I specify the data type of *value, must be the same as data type of handle 00096 * \return error status: CTA_OK, CTA_ILLEGAL_HANDLE, CTA_INCOMPATIBLE_HANDLE 00097 */ 00098 CTAEXPORT int CTA_Handle_GetValue(const CTA_Handle handle, void *value, CTA_Datatype datatype); 00099 00100 /** \brief Get name associated with handle 00101 * 00102 * \param handle I COSTA handle 00103 * \param hname O receives name of data type 00104 * \return error status: CTA_OK, CTA_ILLEGAL_HANDLE 00105 */ 00106 CTAEXPORT int CTA_Handle_GetName(const CTA_Handle handle, CTA_String hname); 00107 00108 /** \brief Get data type associated with handle 00109 * 00110 * \param handle I COSTA handle 00111 * \param datatype O receives data type of handle 00112 * \return error status: CTA_OK, CTA_ILLEGAL_HANDLE 00113 */ 00114 CTAEXPORT int CTA_Handle_GetDatatype(const CTA_Handle handle, CTA_Datatype *datatype); 00115 00116 /** \brief Set name associated with handle (internal use only!) 00117 * 00118 * \param handle IO COSTA handle 00119 * \param name I COSTA string 00120 * \return error status: CTA_OK, CTA_ILLEGAL_HANDLE 00121 */ 00122 CTAEXPORT int CTAI_Handle_SetName(const CTA_Handle handle, const char *name); 00123 00124 /** \brief Find a handle by name and data type in the COSTA handle administration 00125 * 00126 * \param sname I name of handle 00127 * \param datatype I data type of handle 00128 * \param handlenr O receives the handle (only if return value is CTA_OK) 00129 * \return error status: CTA_OK, CTA_HANDLE_NOT_FOUND 00130 */ 00131 CTAEXPORT int CTA_Handle_Find(CTA_String sname, CTA_Datatype datatype, int *handlenr); 00132 00133 /** \brief Print overview of all COSTA handles 00134 * 00135 * \return error status: CTA_OK 00136 */ 00137 CTAEXPORT int CTA_Handle_Printall(); 00138 00139 /** \brief Counts all handles sorts them by type and prints overview. 00140 * This function can be usefull for detecting memory leaks that are 00141 * the result of not freeing instances of COSTA objects costa objects. 00142 * 00143 * \param location I String to indicate location of call 00144 * \return error status: CTA_OK 00145 */ 00146 CTAEXPORT int CTA_Handle_PrintInfo(const char *location); 00147 00148 /** \brief Get the reference count of the handle 00149 * 00150 * \param handle I COSTA handle 00151 * \param refCount O reference count of handle 00152 * \return error status: CTA_OK 00153 * 00154 */ 00155 CTAEXPORT int CTA_Handle_GetRefCount(const CTA_Handle handle, int *refCount); 00156 00157 /** \brief Increase the reference count of the handle 00158 * 00159 * \param handle I COSTA handle 00160 * \return error status: CTA_OK 00161 * 00162 */ 00163 CTAEXPORT int CTA_Handle_IncRefCount(const CTA_Handle handle); 00164 00165 /** \brief Decrease the reference count of the handle 00166 * 00167 * \param handle I COSTA handle 00168 * \return error status: CTA_OK 00169 * 00170 */ 00171 CTAEXPORT int CTA_Handle_DecrRefCount(const CTA_Handle handle); 00172 00173 00174 #ifdef __cplusplus 00175 } 00176 #endif 00177 #endif 00178
1.6.1