fieldml_api.h

Go to the documentation of this file.

/*
 * \file
 * $Id$
 * \author Caton Little
 * \brief 
 *
 * \section LICENSE
 *
 * Version: MPL 1.1/GPL 2.0/LGPL 2.1
 *
 * The contents of this file are subject to the Mozilla 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/MPL/
 *
 * 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 FieldML
 *
 * The Initial Developer of the Original Code is Auckland Uniservices Ltd,
 * Auckland, New Zealand. Portions created by the Initial Developer are
 * Copyright (C) 2010 the Initial Developer. All Rights Reserved.
 *
 * Contributor(s):
 *
 * Alternatively, the contents of this file may be used under the terms of
 * either the GNU General Public License Version 2 or later (the "GPL"), or
 * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
 * in which case the provisions of the GPL or the LGPL are applicable instead
 * of those above. If you wish to allow use of your version of this file only
 * under the terms of either the GPL or the LGPL, and not to allow others to
 * use your version of this file under the terms of the MPL, indicate your
 * decision by deleting the provisions above and replace them with the notice
 * and other provisions required by the GPL or the LGPL. If you do not delete
 * the provisions above, a recipient may use your version of this file under
 * the terms of any one of the MPL, the GPL or the LGPL.
 *
 */
#ifndef H_FIELDML_API
#define H_FIELDML_API

/*

 Typedefs

*/
#ifdef _MSC_VER

typedef __int32 int32_t;
typedef unsigned __int32 uint32_t;
typedef __int64 int64_t;
typedef unsigned __int64 uint64_t;

#else
#include <stdint.h>
#endif


typedef int32_t FmlSessionHandle;               

typedef int32_t FmlObjectHandle;                

typedef int32_t FmlErrorNumber;                 

typedef int32_t FmlBoolean;                     

typedef int32_t FmlEnsembleValue;               


/*

 Constants

*/
#define FML_INVALID_HANDLE -1                   ///< The valid used to indicate a missing object or failed object instantiation.

#define FML_MAJOR_VERSION               0
#define FML_MINOR_VERSION               4
#define FML_DOT_VERSION                 0

#define FML_ERR_NO_ERROR                0       ///< The API call was successful.
#define FML_OK                          0       ///< The API call was successful.
#define FML_ERR_UNKNOWN_HANDLE          1000    ///< An unknown session handle was used.
#define FML_ERR_UNKNOWN_OBJECT          1001    ///< An unknown object handle was used.
#define FML_ERR_INVALID_OBJECT          1002    ///< An object handle referred to an object of the wrong type.
#define FML_ERR_MISCONFIGURED_OBJECT    1003    ///< An object handle referred to an object with an invalid combination of attributes.
#define FML_ERR_ACCESS_VIOLATION        1004    ///< An attempt was made to modify a read-only object (e.g. imported from another region).
#define FML_ERR_NAME_COLLISION          1005    ///< An attempt was made to create an object with a name that was already in use. 
#define FML_ERR_INVALID_REGION          1006    ///< An attempt was made to access an invalid region. This usually indicates a failure to deserialise a FieldML file.
#define FML_ERR_NONLOCAL_OBJECT         1007    ///< An attempt was made to reference a non-local object (i.e. one that has not been imported).
#define FML_ERR_CYCLIC_DEPENDENCY       1008    ///< An attempt was made to create a cyclic dependency.
#define FML_ERR_INVALID_INDEX           1009    ///< An attempt was made to use an out-of-bounds index.
#define FML_ERR_READ_ERR                1010    ///< A read error was encountered during IO.

//Used for giving the user precise feedback on bad parameters passed to the API
//Only used for parameters other than the FieldML handle and object handle parameters.
#define FML_ERR_INVALID_PARAMETERS      1100    ///< A general-purpose error code indicating that some parameters to the API call were invalid.
#define FML_ERR_INVALID_PARAMETER_1     1101    ///< A general-purpose error code indicating that the first parameter to the API call was invalid.
#define FML_ERR_INVALID_PARAMETER_2     1102    ///< A general-purpose error code indicating that the second parameter to the API call was invalid.
#define FML_ERR_INVALID_PARAMETER_3     1103    ///< A general-purpose error code indicating that the third parameter to the API call was invalid.
#define FML_ERR_INVALID_PARAMETER_4     1104    ///< A general-purpose error code indicating that the fourth parameter to the API call was invalid.
#define FML_ERR_INVALID_PARAMETER_5     1105    ///< A general-purpose error code indicating that the fifth parameter to the API call was invalid.
#define FML_ERR_INVALID_PARAMETER_6     1106    ///< A general-purpose error code indicating that the sixth parameter to the API call was invalid.
#define FML_ERR_INVALID_PARAMETER_7     1107    ///< A general-purpose error code indicating that the seventh parameter to the API call was invalid.
#define FML_ERR_INVALID_PARAMETER_8     1108    ///< A general-purpose error code indicating that the eigth parameter to the API call was invalid.

#define FML_ERR_UNSUPPORTED             2000    ///< Used for operations that are valid, but not yet implemented.

/*

 Types

*/


enum FieldmlEnsembleMembersType
{
    FML_ENSEMBLE_MEMBER_UNKNOWN,           
    FML_ENSEMBLE_MEMBER_RANGE,             
    FML_ENSEMBLE_MEMBER_LIST_DATA,         
    FML_ENSEMBLE_MEMBER_RANGE_DATA,        
    FML_ENSEMBLE_MEMBER_STRIDE_RANGE_DATA, 
};


enum FieldmlDataDescriptionType
{
    FML_DATA_DESCRIPTION_UNKNOWN,      
    FML_DATA_DESCRIPTION_DENSE_ARRAY,  
    FML_DATA_DESCRIPTION_DOK_ARRAY,    
};


enum FieldmlDataResourceType
{
    FML_DATA_RESOURCE_UNKNOWN,     
    FML_DATA_RESOURCE_HREF,        
    FML_DATA_RESOURCE_INLINE,      
};


enum FieldmlDataSourceType
{
    FML_DATA_SOURCE_UNKNOWN,      
    FML_DATA_SOURCE_ARRAY,        
};


enum FieldmlHandleType
{
    FHT_UNKNOWN,              
    
    FHT_ENSEMBLE_TYPE,        
    FHT_CONTINUOUS_TYPE,      
    FHT_MESH_TYPE,            
    FHT_BOOLEAN_TYPE,         
    FHT_ARGUMENT_EVALUATOR,   
    FHT_EXTERNAL_EVALUATOR,   
    FHT_REFERENCE_EVALUATOR,  
    FHT_PARAMETER_EVALUATOR,  
    FHT_PIECEWISE_EVALUATOR,  
    FHT_AGGREGATE_EVALUATOR,  
    FHT_CONSTANT_EVALUATOR,   
    FHT_DATA_RESOURCE,        
    FHT_DATA_SOURCE,          
};


/*

 API

*/

#ifdef __cplusplus
extern "C" {
#endif //__cplusplus


FmlSessionHandle Fieldml_CreateFromFile( const char * filename );


FmlSessionHandle Fieldml_Create( const char * location, const char * name );


FmlErrorNumber Fieldml_SetDebug( FmlSessionHandle handle, int debug );


FmlErrorNumber Fieldml_GetLastError( FmlSessionHandle handle );


FmlErrorNumber Fieldml_WriteFile( FmlSessionHandle handle, const char * filename );


void Fieldml_Destroy( FmlSessionHandle handle );


FmlErrorNumber Fieldml_FreeString( char * string );


char * Fieldml_GetRegionName( FmlSessionHandle handle );


int Fieldml_CopyRegionName( FmlSessionHandle handle, char * buffer, int bufferLength );


char * Fieldml_GetRegionRoot( FmlSessionHandle handle );


int Fieldml_CopyRegionRoot( FmlSessionHandle handle, char * buffer, int bufferLength );

int Fieldml_GetErrorCount( FmlSessionHandle handle );


char * Fieldml_GetError( FmlSessionHandle handle, int index );


int Fieldml_CopyError( FmlSessionHandle handle, int errorIndex, char * buffer, int bufferLength );


FmlErrorNumber Fieldml_ClearErrors( FmlSessionHandle handle );


int Fieldml_GetTotalObjectCount( FmlSessionHandle handle );


FmlObjectHandle Fieldml_GetObjectByIndex( FmlSessionHandle handle, const int objectIndex );


int Fieldml_GetObjectCount( FmlSessionHandle handle, FieldmlHandleType type );


FmlObjectHandle Fieldml_GetObject( FmlSessionHandle handle, FieldmlHandleType objectType, int objectIndex );


FieldmlHandleType Fieldml_GetObjectType( FmlSessionHandle handle, FmlObjectHandle objectHandle );


FmlObjectHandle Fieldml_GetObjectByName( FmlSessionHandle handle, const char * name );


FmlObjectHandle Fieldml_GetObjectByDeclaredName( FmlSessionHandle handle, const char * name );

FmlBoolean Fieldml_IsObjectLocal( FmlSessionHandle handle, FmlObjectHandle objectHandle, FmlBoolean isDeclaredOnly );


char * Fieldml_GetObjectName( FmlSessionHandle handle, FmlObjectHandle objectHandle );


int Fieldml_CopyObjectName( FmlSessionHandle handle, FmlObjectHandle objectHandle, char * buffer, int bufferLength );


char * Fieldml_GetObjectDeclaredName( FmlSessionHandle handle, FmlObjectHandle objectHandle );


int Fieldml_CopyObjectDeclaredName( FmlSessionHandle handle, FmlObjectHandle objectHandle, char * buffer, int bufferLength );


FmlErrorNumber Fieldml_SetObjectInt( FmlSessionHandle handle, FmlObjectHandle objectHandle, int value );


int Fieldml_GetObjectInt( FmlSessionHandle handle, FmlObjectHandle objectHandle );


FmlObjectHandle Fieldml_GetTypeComponentEnsemble( FmlSessionHandle handle, FmlObjectHandle objectHandle );


int Fieldml_GetTypeComponentCount( FmlSessionHandle handle, FmlObjectHandle objectHandle );


FmlObjectHandle Fieldml_CreateEnsembleType( FmlSessionHandle handle, const char * name );


FmlObjectHandle Fieldml_CreateBooleanType( FmlSessionHandle handle, const char * name );


FmlObjectHandle Fieldml_CreateContinuousType( FmlSessionHandle handle, const char * name );


FmlObjectHandle Fieldml_CreateContinuousTypeComponents( FmlSessionHandle handle, FmlObjectHandle typeHandle, const char * name, const int count );

FmlObjectHandle Fieldml_CreateMeshType( FmlSessionHandle handle, const char * name );

FmlObjectHandle Fieldml_CreateMeshElementsType( FmlSessionHandle handle, FmlObjectHandle meshHandle, const char * name );

FmlObjectHandle Fieldml_CreateMeshChartType( FmlSessionHandle handle, FmlObjectHandle meshHandle, const char * name );


FmlObjectHandle Fieldml_GetMeshChartType( FmlSessionHandle handle, FmlObjectHandle meshHandle );


FmlObjectHandle Fieldml_GetMeshChartComponentType( FmlSessionHandle handle, FmlObjectHandle meshHandle );


FmlObjectHandle Fieldml_GetMeshElementsType( FmlSessionHandle handle, FmlObjectHandle meshHandle );


FmlObjectHandle Fieldml_GetMeshShapes( FmlSessionHandle handle, FmlObjectHandle meshHandle );


FmlErrorNumber Fieldml_SetMeshShapes( FmlSessionHandle handle, FmlObjectHandle meshHandle, FmlObjectHandle shapesHandle );


FmlBoolean Fieldml_IsEnsembleComponentType( FmlSessionHandle handle, FmlObjectHandle objectHandle );


FmlObjectHandle Fieldml_GetValueType( FmlSessionHandle handle, FmlObjectHandle objectHandle );


FmlObjectHandle Fieldml_CreateArgumentEvaluator( FmlSessionHandle handle, const char * name, FmlObjectHandle valueType );


FmlObjectHandle Fieldml_CreateExternalEvaluator( FmlSessionHandle handle, const char * name, FmlObjectHandle valueType );


FmlObjectHandle Fieldml_CreateParameterEvaluator( FmlSessionHandle handle, const char * name, FmlObjectHandle valueType );


FmlErrorNumber Fieldml_SetParameterDataDescription( FmlSessionHandle handle, FmlObjectHandle objectHandle, FieldmlDataDescriptionType description );

FmlObjectHandle Fieldml_GetDataSource( FmlSessionHandle handle, FmlObjectHandle objectHandle );

FmlObjectHandle Fieldml_GetKeyDataSource( FmlSessionHandle handle, FmlObjectHandle objectHandle );

FmlErrorNumber Fieldml_SetDataSource( FmlSessionHandle handle, FmlObjectHandle objectHandle, FmlObjectHandle dataSource );


FmlErrorNumber Fieldml_SetKeyDataSource( FmlSessionHandle handle, FmlObjectHandle objectHandle, FmlObjectHandle dataSource );


FieldmlDataDescriptionType Fieldml_GetParameterDataDescription( FmlSessionHandle handle, FmlObjectHandle objectHandle );


FmlErrorNumber Fieldml_AddDenseIndexEvaluator( FmlSessionHandle handle, FmlObjectHandle objectHandle, FmlObjectHandle indexHandle, FmlObjectHandle orderHandle );

FmlErrorNumber Fieldml_AddSparseIndexEvaluator( FmlSessionHandle handle, FmlObjectHandle objectHandle, FmlObjectHandle indexHandle );


int Fieldml_GetParameterIndexCount( FmlSessionHandle handle, FmlObjectHandle objectHandle, FmlBoolean isSparse );


FmlObjectHandle Fieldml_GetParameterIndexEvaluator( FmlSessionHandle handle, FmlObjectHandle objectHandle, int index, FmlBoolean isSparse );


FmlObjectHandle Fieldml_GetParameterIndexOrder( FmlSessionHandle handle, FmlObjectHandle objectHandle, int index );

FmlObjectHandle Fieldml_CreatePiecewiseEvaluator( FmlSessionHandle handle, const char * name, FmlObjectHandle valueType );


FmlObjectHandle Fieldml_CreateAggregateEvaluator( FmlSessionHandle handle, const char * name, FmlObjectHandle valueType );


FmlErrorNumber Fieldml_SetIndexEvaluator( FmlSessionHandle handle, FmlObjectHandle objectHandle, int index, FmlObjectHandle evaluatorHandle );

FmlErrorNumber Fieldml_SetDefaultEvaluator( FmlSessionHandle handle, FmlObjectHandle objectHandle, FmlObjectHandle evaluator );


FmlObjectHandle Fieldml_GetDefaultEvaluator( FmlSessionHandle handle, FmlObjectHandle objectHandle );


FmlErrorNumber Fieldml_SetEvaluator( FmlSessionHandle handle, FmlObjectHandle objectHandle, FmlEnsembleValue element, FmlObjectHandle evaluator );


int Fieldml_GetEvaluatorCount( FmlSessionHandle handle, FmlObjectHandle objectHandle );


FmlEnsembleValue Fieldml_GetEvaluatorElement( FmlSessionHandle handle, FmlObjectHandle objectHandle, int evaluatorIndex );


FmlObjectHandle Fieldml_GetEvaluator( FmlSessionHandle handle, FmlObjectHandle objectHandle, int evaluatorIndex );


FmlObjectHandle Fieldml_GetElementEvaluator( FmlSessionHandle handle, FmlObjectHandle objectHandle, FmlEnsembleValue elementNumber, FmlBoolean allowDefault );


int Fieldml_GetIndexEvaluatorCount( FmlSessionHandle handle, FmlObjectHandle objectHandle );


FmlObjectHandle Fieldml_GetIndexEvaluator( FmlSessionHandle handle, FmlObjectHandle objectHandle, int indexNumber );


FmlObjectHandle Fieldml_CreateReferenceEvaluator( FmlSessionHandle handle, const char * name, FmlObjectHandle sourceEvaluator );


FmlObjectHandle Fieldml_GetReferenceSourceEvaluator( FmlSessionHandle handle, FmlObjectHandle objectHandle );


FmlErrorNumber Fieldml_AddArgument( FmlSessionHandle handle, FmlObjectHandle objectHandle, FmlObjectHandle evaluatorHandle );


int Fieldml_GetArgumentCount( FmlSessionHandle handle, FmlObjectHandle objectHandle, FmlBoolean isBound, FmlBoolean isUsed );


FmlObjectHandle Fieldml_GetArgument( FmlSessionHandle handle, FmlObjectHandle objectHandle, int argumentIndex, FmlBoolean isBound, FmlBoolean isUsed );


FmlErrorNumber Fieldml_SetBind( FmlSessionHandle handle, FmlObjectHandle objectHandle, FmlObjectHandle argumentHandle, FmlObjectHandle sourceHandle );


int Fieldml_GetBindCount( FmlSessionHandle handle, FmlObjectHandle objectHandle );


FmlObjectHandle Fieldml_GetBindArgument( FmlSessionHandle handle, FmlObjectHandle objectHandle, int bindIndex );


FmlObjectHandle Fieldml_GetBindEvaluator( FmlSessionHandle handle, FmlObjectHandle objectHandle, int bindIndex );


FmlObjectHandle Fieldml_GetBindByArgument( FmlSessionHandle handle, FmlObjectHandle objectHandle, FmlObjectHandle argumentHandle );



FieldmlEnsembleMembersType Fieldml_GetEnsembleMembersType( FmlSessionHandle handle, FmlObjectHandle objectHandle );


FmlErrorNumber Fieldml_SetEnsembleMembersDataSource( FmlSessionHandle handle, FmlObjectHandle objectHandle, FieldmlEnsembleMembersType type, int count, FmlObjectHandle dataSourceHandle );

FmlErrorNumber Fieldml_SetEnsembleMembersRange( FmlSessionHandle handle, FmlObjectHandle objectHandle, const FmlEnsembleValue minElement, const FmlEnsembleValue maxElement, const int stride );


int Fieldml_GetMemberCount( FmlSessionHandle handle, FmlObjectHandle objectHandle );


FmlEnsembleValue Fieldml_GetEnsembleMembersMin( FmlSessionHandle handle, FmlObjectHandle objectHandle );


FmlEnsembleValue Fieldml_GetEnsembleMembersMax( FmlSessionHandle handle, FmlObjectHandle objectHandle );


int Fieldml_GetEnsembleMembersStride( FmlSessionHandle handle, FmlObjectHandle objectHandle );


int Fieldml_AddImportSource( FmlSessionHandle handle, const char * href, const char * regionName );


FmlObjectHandle Fieldml_AddImport( FmlSessionHandle handle, int importSourceIndex, const char * localName, const char * remoteName );


int Fieldml_GetImportSourceCount( FmlSessionHandle handle );


int Fieldml_CopyImportSourceHref( FmlSessionHandle handle, int importSourceIndex, char * buffer, int bufferLength );


int Fieldml_CopyImportSourceRegionName( FmlSessionHandle handle, int importSourceIndex, char * buffer, int bufferLength );


int Fieldml_GetImportCount( FmlSessionHandle handle, int importSourceIndex );


int Fieldml_CopyImportLocalName( FmlSessionHandle handle, int importSourceIndex, int importIndex, char * buffer, int bufferLength );


int Fieldml_CopyImportRemoteName( FmlSessionHandle handle, int importSourceIndex, int importIndex, char * buffer, int bufferLength );


FmlObjectHandle Fieldml_GetImportObject( FmlSessionHandle handle, int importSourceIndex, int importIndex );


FmlObjectHandle Fieldml_CreateHrefDataResource( FmlSessionHandle handle, const char * name, const char * format, const char * href );

FmlObjectHandle Fieldml_CreateInlineDataResource( FmlSessionHandle handle, const char * name );


FieldmlDataResourceType Fieldml_GetDataResourceType( FmlSessionHandle handle, FmlObjectHandle objectHandle );


FmlObjectHandle Fieldml_CreateArrayDataSource( FmlSessionHandle handle, const char * name, FmlObjectHandle resourceHandle, const char * location, int rank );

int Fieldml_GetDataSourceCount( FmlSessionHandle handle, FmlObjectHandle objectHandle );


FmlObjectHandle Fieldml_GetDataSourceByIndex( FmlSessionHandle handle, FmlObjectHandle objectHandle, int index );


FmlObjectHandle Fieldml_GetDataSourceResource( FmlSessionHandle handle, FmlObjectHandle objectHandle );


char * Fieldml_GetArrayDataSourceLocation( FmlSessionHandle handle, FmlObjectHandle objectHandle );

int Fieldml_CopyArrayDataSourceLocation( FmlSessionHandle handle, FmlObjectHandle objectHandle, char * buffer, int bufferLength );


int Fieldml_GetArrayDataSourceRank( FmlSessionHandle handle, FmlObjectHandle objectHandle );


FmlErrorNumber Fieldml_GetArrayDataSourceRawSizes( FmlSessionHandle handle, FmlObjectHandle objectHandle, int *sizes );


FmlErrorNumber Fieldml_SetArrayDataSourceRawSizes( FmlSessionHandle handle, FmlObjectHandle objectHandle, int *sizes );

FmlErrorNumber Fieldml_GetArrayDataSourceOffsets( FmlSessionHandle handle, FmlObjectHandle objectHandle, int *offsets );


FmlErrorNumber Fieldml_SetArrayDataSourceOffsets( FmlSessionHandle handle, FmlObjectHandle objectHandle, int *offsets );


FmlErrorNumber Fieldml_GetArrayDataSourceSizes( FmlSessionHandle handle, FmlObjectHandle objectHandle, int *sizes );


FmlErrorNumber Fieldml_SetArrayDataSourceSizes( FmlSessionHandle handle, FmlObjectHandle objectHandle, int *sizes );


FieldmlDataSourceType Fieldml_GetDataSourceType( FmlSessionHandle handle, FmlObjectHandle objectHandle );


FmlErrorNumber Fieldml_AddInlineData( FmlSessionHandle handle, FmlObjectHandle objectHandle, const char * data, const int length );


FmlErrorNumber Fieldml_SetInlineData( FmlSessionHandle handle, FmlObjectHandle objectHandle, const char * data, const int length );


int Fieldml_GetInlineDataLength( FmlSessionHandle handle, FmlObjectHandle objectHandle );


char * Fieldml_GetInlineData( FmlSessionHandle handle, FmlObjectHandle objectHandle );


int Fieldml_CopyInlineData( FmlSessionHandle handle, FmlObjectHandle objectHandle, char * buffer, int bufferLength, int offset );

char * Fieldml_GetDataResourceHref( FmlSessionHandle handle, FmlObjectHandle objectHandle );


int Fieldml_CopyDataResourceHref( FmlSessionHandle handle, FmlObjectHandle objectHandle, char * buffer, int bufferLength );

char * Fieldml_GetDataResourceFormat( FmlSessionHandle handle, FmlObjectHandle objectHandle );


int Fieldml_CopyDataResourceFormat( FmlSessionHandle handle, FmlObjectHandle objectHandle, char * buffer, int bufferLength );


int Fieldml_CreateConstantEvaluator( FmlSessionHandle handle, const char * name, const char * literal, FmlObjectHandle valueType );


char * Fieldml_GetConstantEvaluatorValueString( FmlSessionHandle handle, FmlObjectHandle objectHandle );


int Fieldml_CopyConstantEvaluatorValueString( FmlSessionHandle handle, FmlObjectHandle objectHandle, char * buffer, int bufferLength );

#ifdef __cplusplus
}
#endif // __cplusplus

#endif // H_FIELDML_API