A3DSDKTools.h

Header of A3DSDK.

Tool section.

Author

Tech Soft 3D

Version

23.0

Date

January 2023

Copyright (c) 2010 - 2023 by Tech Soft 3D, Inc. All rights reserved.

Content

Data Structures

A3DCopyAndAdaptBrepModelData	Copy and convert to NURBS parameter.
A3DCopyAndAdaptBrepModelErrorData	Copy and convert to NURBS error result.
A3DTopoItemOwner	Structure is a linked list for storing topology items owners.
A3DPhysicalPropertiesData	Physical property settings.

Functions

A3DCopyAndAdaptBrepModel()	Copy and adapt B-rep parameters.
A3DCopyAndAdaptBrepModelAdvanced()	Copy and adapt B-rep parameters.
A3DAdaptAndReplaceAllBrepInModelFile()	Entity Convert to NURBS facility.
A3DAdaptAndReplaceAllBrepInModelFileAdvanced()	Entity Convert to NURBS facility.
A3DEntityDelete()	Recursively deletes the entity and its child entities.
A3DEntityGetPDFNodeIdFromWrite()	Gets the PDF node unique IDs for the entities.
A3DEntityGetPDFNodeIdFromRead()	Gets the PDF node unique IDs for the entities.
A3DTopoItemOwnersManagerGet()	Structure for storing topology items owners.
A3DTopoItemOwnersGet()	Gets owners of topology item.
A3DComputePhysicalProperties()	Function to compute the physical properties (surface area, volume and gravity center, and since 11.2 the surfacic gravity center and the surfacic and volumic inertia matrix) of a BrepModel.
A3DComputeFaceArea()	Function to compute the surface of the current A3DTopoFace.
A3DComputePolyBrepPhysicalProperties()	Function to compute the physical properties (surface area, volume and gravity center, and since 11.2 the surfacic gravity center and the surfacic and volumic inertia matrix) of a PolyBrepModel.
A3DComputeModelFilePhysicalProperties()	Function to compute the physical properties (surface area, volume and gravity center, and since 11.2 the surfacic gravity center and the surfacic and volumic inertia matrix) of a modelfile, typically an assembly.
A3DSimplifyModelFileCurveAndSurfaceAsAnalytic()	Function to traverse the entire modelfile and simplify all curves and surfaces to analytics if possible, according to a certain tolerance.
A3DSimplifyModelFileWithAnalytics()	Function to traverse the entire modelfile and simplify all curves and surfaces to analytics if possible, according to a certain tolerance.

Functions

A3DStatus A3DCopyAndAdaptBrepModel(const A3DEntity *p, const A3DCopyAndAdaptBrepModelData *psSetting, A3DEntity **const pp)

Copy and adapt B-rep parameters.

The B-rep used by HOOPS Exchange may not be completely compatible with modeling systems that do not support the full range of B-rep as employed by PRC. This function attempts to convert PRC B-rep into a format that is compatible with your system.

In order to use this function, you create a A3DCopyAndAdaptBrepModelData structure and configure it to create a new B-rep model using entities you are able to support. The function can transform predetermined surface types and curves to NURBS. It also can process parametric curves and 3D curves, as well as split periodic parametric surfaces.

Finally, it creates a new B-rep model. After using it, the new model should be deleted.

A3DCopyAndAdaptBrepModel will perform the following steps:

• For each face, the bearing surface and the 3D curves are converted

• Surfaces are reduced in size

• Cross-period UV curves are deleted if necessary

• Faces are split at periodic seams and/or mid-parameter for closed surfaces

• Final UV curves are computed

• A second surface shrink is performed with new UV parameters

• Final 3D curves are computed

Note

When the function A3DCopyAndAdaptBrepModel returns an error, you may try to set the parameters m_bSplitFaces and/or m_bForceComputeUV to ‘false’ and retry the conversion.

Parameters

• p – [in] A pointer to the source B-rep entity

• psSetting – [in] The structure that defines which types of B-rep you would like to convert to

• pp – [out] A pointer to the result B-rep entity or entities

Return values

• A3D_INVALID_ENTITY_TYPE –

• A3D_SRF_INVALID_PARAMETERS –

• A3D_CRV_INVALID_PARAMETER –

• A3D_ERROR –

• A3D_SUCCESS –

• A3D_INITIALIZE_BAD_VALUES –

• A3D_NOT_IMPLEMENTED –

• A3D_TOPO_VERTICES_MISSING –

• A3D_COEDGE_BAD_ORIENTATION_DATA –

• A3D_TOPO_GEOMETRY_MISSING –

• A3D_LOOP_BAD_ORIENTATION_DATA –

• A3D_SHELL_BAD_ORIENTATION_DATA –

• A3D_TOPO_WRONG_TOLERANCES –

• A3D_TOPO_CONSISTENCY –

• A3D_TOPO_NON_CONNEX_SHELL –

• A3D_TOPO_OPEN_SOLID –

• A3D_TOOLS_NURBSCONVERT_SURFACE_FAILURE –

• A3D_TOOLS_NURBSCONVERT_UV_FAILURE –

• A3D_TOOLS_NURBSCONVERT_3D_FAILURE –

• A3D_TOOLS_NURBSCONVERT_GENERAL_FAILURE –

• A3D_TOOLS_SPLIT_FAILURE –

• A3D_TOOLS_COMPUTE_UV_FAILURE –

• A3D_TOOLS_COMPUTE_3D_FAILURE –

• A3D_INVALID_ENTITY_NULL –

• A3D_EXCEPTION –

• A3D_BREPDATA_CANNOT_GETBOUNDINGBOX –

• A3D_INCOMPATIBLE_FUNCTION_WITH_KEEP_PARSED_ENTITY_MODE –

Returns

A3D_SUCCESS in case of success or an error code

A3DStatus A3DCopyAndAdaptBrepModelAdvanced(const A3DEntity *p, const A3DCopyAndAdaptBrepModelData *psSetting, A3DEntity **const pp, A3DUns32 *puiNbErrors, A3DInt32 **paiErrors)

Copy and adapt B-rep parameters.

Same as A3DCopyAndAdaptBrepModelData , but return status of each face in error if A3DCopyAndAdaptBrepModelData::m_bContinueOnError is set to true

puiNbErrors return the number of faces in error

paiErrors corresponds to a set of indexes and error codes paiErrors[0] = type the topological element paiErrors[1] = error status paiErrors[2] = number of indexes to find element (connex = 1, shell = 2, face = 3, loop = 4, coedge /edge = 5) paiErrors[3] = first index ... paiErrors[2+paiErrors[2]] = last index

Parameters

• p – [in] A pointer to the source B-rep entity

• psSetting – [in] The structure that defines which types of B-rep you would like to convert to

• pp – [out] A pointer to the result B-rep entity or entities

• puiNbErrors – [out] Number of elements in error

• paiErrors – [out] Index and error code of each element

Return values

• A3D_INVALID_ENTITY_TYPE –

• A3D_SRF_INVALID_PARAMETERS –

• A3D_CRV_INVALID_PARAMETER –

• A3D_ERROR –

• A3D_SUCCESS –

• A3D_INITIALIZE_BAD_VALUES –

• A3D_NOT_IMPLEMENTED –

• A3D_TOPO_VERTICES_MISSING –

• A3D_COEDGE_BAD_ORIENTATION_DATA –

• A3D_TOPO_GEOMETRY_MISSING –

• A3D_LOOP_BAD_ORIENTATION_DATA –

• A3D_SHELL_BAD_ORIENTATION_DATA –

• A3D_TOPO_WRONG_TOLERANCES –

• A3D_TOPO_CONSISTENCY –

• A3D_TOPO_NON_CONNEX_SHELL –

• A3D_TOPO_OPEN_SOLID –

• A3D_TOOLS_NURBSCONVERT_SURFACE_FAILURE –

• A3D_TOOLS_NURBSCONVERT_UV_FAILURE –

• A3D_TOOLS_NURBSCONVERT_3D_FAILURE –

• A3D_TOOLS_NURBSCONVERT_GENERAL_FAILURE –

• A3D_TOOLS_SPLIT_FAILURE –

• A3D_TOOLS_COMPUTE_UV_FAILURE –

• A3D_TOOLS_COMPUTE_3D_FAILURE –

• A3D_INVALID_ENTITY_NULL –

• A3D_EXCEPTION –

• A3D_BREPDATA_CANNOT_GETBOUNDINGBOX –

• A3D_INCOMPATIBLE_FUNCTION_WITH_KEEP_PARSED_ENTITY_MODE –

Returns

A3D_SUCCESS in case of success or an error code

A3DStatus A3DAdaptAndReplaceAllBrepInModelFile(A3DAsmModelFile *pModelFile, const A3DCopyAndAdaptBrepModelData *psSetting)

Entity Convert to NURBS facility.

These are the steps performed, according to the settings in A3DCopyAndAdaptBrepModelData:

• For each face, the bearing surface is converted and then the 3D curves that are present

• Surfaces are shrinked.

• Cross-period UV curves are deleted if needed.

• Faces are split at periodic seams and/or mid-parameter for closed surfaces.

• Final UV curves are computed.

• A second surface shrink is performed with new UVs.

• Final 3D curves are computed.

In case where psSetting->m_bContinueOnError is A3D_TRUE, the function does not return any error code, unless it is considered as a fatal error. In that case, if you wish to know when an error occurs, use A3DAdaptAndReplaceAllBrepInModelFileAdvanced instead. Then check its puiNbErrors parameter.

See also

A3DAdaptAndReplaceAllBrepInModelFileAdvanced

Version

5.2

Note

When the function A3AdaptAndReplaceAllBrepInModelFile ends in error, you may try to set the parameters m_bSplitFaces and/or m_bForceComputeUV to A3D_FALSE and retry the conversion.

Parameters

• pModelFile – [in] The source model file to adapt.

• psSetting – [in] The structure that defines which types of B-rep you would like to convert to.

Return values

• A3D_CRV_INVALID_PARAMETER – if psSetting ->m_puiAcceptableCurves contains invalid types.

• A3D_SRF_INVALID_PARAMETERS – if psSetting->m_puiAcceptableSurfaces contains invalid types.

• A3D_TOOLS_NURBSCONVERT_GENERAL_FAILURE – This function adapts all B-rep in a Model File to customers’ needs. It enables the transformation of predetermined types of surfaces and curves as NURBS. It also permits computation of parametric curves and/or 3D curves, splitting periodic surfaces, etc.

Returns

A3D_SUCCESS in case of success or an error code

A3DStatus A3DAdaptAndReplaceAllBrepInModelFileAdvanced(A3DAsmModelFile *p, const A3DCopyAndAdaptBrepModelData *psSetting, A3DUns32 *puiNbErrors, A3DCopyAndAdaptBrepModelErrorData **pErrors)

Entity Convert to NURBS facility.

Same as A3DAdaptAndReplaceAllBrepInModelFile , but return status of each element in error if A3DCopyAndAdaptBrepModelData::m_bContinueOnError is set to true

puiNbErrors return the number of brep in error

pErrors corresponds to the list of error for each brep

Version

9.2

Parameters

• p – [in] A pointer to the model file

• psSetting – [in] The structure that defines which types of B-rep you would like to convert to

• puiNbErrors – [out] Number of brep in error

• pErrors – [out] list of errors for each brep

Return values

• A3D_TOOLS_CONTINUE_ON_ERROR – if there is errors, but A3DCopyAndAdaptBrepModelData.m_bContinueOnError is set to true

• A3D_INCOMPATIBLE_FUNCTION_WITH_KEEP_PARSED_ENTITY_MODE –

Returns

A3D_SUCCESS in case of success or an error code

A3DStatus A3DEntityDelete(A3DEntity *pEntity)

Recursively deletes the entity and its child entities.

This function deletes the given entity along with all it’s child entities. Usually deleting any entity of a PRC tree is implicitly done when the tree root is deleted using A3DAsmModelFileDelete. However, it is possible that some entities may not be attached to any PRC. This is usually the case when a CAD model is manipulated for modification purpose.

As a rule of thumb, you should always explicitly delete an entity you did’nt attach to any other entity.

Remark

Some entity types require a specific function for deletion. Please see:

• A3DFaceUVPointInsideManagerDelete

• A3DFileContextDelete

• A3DMiscCascadedAttributesDelete

• A3DMkpRTFDelete

• A3DMkpRTFFieldDelete

• A3DProjectPointCloudManagerDelete

Warning

This function must be called only on detached entities. Using it on an attached entity will resulting in a double free error when the PRC tree is deleted.

Warning

This function must not be applied within an HOOPS Visualize context. See Quickstart.

Return values

A3D_SUCCESS –

Returns

A3D_SUCCESS in case of success or an error code

A3DStatus A3DEntityGetPDFNodeIdFromWrite(const A3DEntity *pEntity, const A3DEntity *pEntityFather, const A3DRWParamsPrcWriteHelper *pA3DRWParamsPrcWriteHelper, A3DUTF8Char **pcUTF8Name)

Gets the PDF node unique IDs for the entities.

Given a pointer to the PRC entity, this function gets the unique name that will be used in the PDF scene graph. This function must be used AFTER the PRC file has been created from the model file.

Version

4.1

Parameters

• pEntity – [in] The pointer to the PRC entity

• pEntityFather – [in] The pointer to the product occurrence owner to the PRC entity. NULL if pEntity is a product occurrence.

• pA3DRWParamsPrcWriteHelper – [in] The pointer to the helper object generally built by the function A3DAsmModelFileExportToPrcFile.

• pcUTF8Name – [out] The identifier as a string.

Return values

A3D_SUCCESS –

Returns

A3D_SUCCESS in case of success or an error code

A3DStatus A3DEntityGetPDFNodeIdFromRead(const A3DEntity *pEntity, const A3DEntity *pEntityFather, const A3DRWParamsPrcReadHelper *pA3DRWParamsPrcReadHelper, A3DUTF8Char **pcUTF8Name)

Gets the PDF node unique IDs for the entities.

Given a pointer to the PRC entity, this function gets the unique name that will be used in the PDF scene graph. This function must be used AFTER the PRC file has been created from the model file.

Version

9.2

Parameters

• pEntity – [in] The pointer to the PRC entity

• pEntityFather – [in] The pointer to the product occurrence owner to the PRC entity. NULL if pEntity is a product occurrence.

• pA3DRWParamsPrcReadHelper – [in] The pointer to the helper object generally built by the function A3DAsmModelFileLoadFromPrcStream.

• pcUTF8Name – [out] The identifier as a string.

Return values

A3D_SUCCESS –

Returns

A3D_SUCCESS in case of success or an error code

A3DStatus A3DTopoItemOwnersManagerGet(const A3DRiRepresentationItem *pBrepOwner, A3DTopoItemOwnersManager **ppTopoItemOwnersManager)

Structure for storing topology items owners.

Creates manager of topology items fron an A3DRiRepresentationItem

Version

5.0 Methods and structures dedicated to managing the link between topology items and their owner(s).

// map creation
A3DTopoItemOwnersManager* pTopologyOwnersManager = NULL;
if(A3DTopoItemOwnersManagerGet(pBrepOwner, pTopologyOwnersManager) != A3D_SUCCESS)
    return A3D_ERROR;
if(pTopologyOwnersManager == NULL)
    return A3D_ERROR;

// edge owners = CoEdge
A3DTopoItemOwner* pOwningCoEdge = NULL;
A3DTopoItemOwnersGet(pTopologyOwnersManager, pEdge, pOwningCoEdge);
while( pOwningCoEdge!=NULL)
{
    // coedge owners = Loop
    A3DTopoItemOwner* pOwningLoop = NULL;
    A3DTopoItemOwnersGet(pTopologyOwnersManager, pOwningCoEdge->m_pTopoItem, pOwningLoop);
    while( pOwningLoop!=NULL)
    {
        // Loop owners = face
        A3DTopoItemOwner* pOwingFace = NULL;
        A3DTopoItemOwnersGet(pTopologyOwnersManager, pOwningLoop->m_pTopoItem, pOwingFace);
        while( pOwingFace!=NULL)
        {
            if(A3DEntityGetType(pOwingFace->m_pTopoItem, &entityType) != A3D_SUCCESS)
                return A3D_ERROR;
            if(entityType != kA3DTypeTopoFace)
                return A3D_ERROR;

            pOwingFace = pOwingFace->m_pNext;
        }
        pOwningLoop = pOwningLoop->m_pNext;
    }
    pOwningCoEdge = pOwningCoEdge->m_pNext;
}

Version

5.0

This function creates a map, on request, between topological items and linked lists of owners. When the map is built, the function A3DTopoItemOwnersGet lets you retrieve owners of specific topological item. For example, if you need the faces owner of edges, first you build your map, then you retrieve the owner list for each edge. The following code shows how to use it.

Note that, if A3DTopoItemOwnersManagerGet is called several times with the same representation item, the map is not recomputed; and if the representation item is null, the map is released.

Return values

• A3D_SUCCESS –

• A3D_INVALID_ENTITY_TYPE –

• A3D_ERROR –

Returns

A3D_SUCCESS in case of success or an error code

A3DStatus A3DTopoItemOwnersGet(A3DTopoItemOwnersManager *pTopoItemOwnersManager, const A3DTopoItem *pTopoItem, A3DTopoItemOwner **ppTopoItemOwner)

Gets owners of topology item.

Version

5.0

Return values

• A3D_SUCCESS –

• A3D_INVALID_ENTITY_TYPE –

• A3D_ERROR –

Returns

A3D_SUCCESS in case of success or an error code

A3DStatus A3DComputePhysicalProperties(const A3DRiBrepModel *p, const A3DVector3dData *psScale, A3DPhysicalPropertiesData *psPhysicalPropertiesData)

Function to compute the physical properties (surface area, volume and gravity center, and since 11.2 the surfacic gravity center and the surfacic and volumic inertia matrix) of a BrepModel.

To obtain the values in the unit of the model file, pass the scaling of the B-rep in the psScale parameter.

Note that since 11.2, the input psPhysicalPropertiesData structure now has a couple of input parameters with which precision can be adjusted, in addition to the new return values.

The value of psScale should be the cumulative scaling that results from traversing the assembly tree from the root to the designated B-rep, multiplying the scaling of the current node by the cumulative scaling of all of its parent nodes.

The inertia matrices are provided relative to the computed gravity centers, with respect to the global X, Y and Z directions.

Version

5.2

Parameters

• p – [in] The input B-rep model.

• psScale – [in] The optional scale.

• psPhysicalPropertiesData – [out] The computed physical properties.

Return values

• A3D_SUCCESS –

• A3D_INITIALIZE_NOT_CALLED –

• A3D_INVALID_ENTITY_NULL –

• A3D_INVALID_ENTITY_TYPE –

• A3D_RI_BREPMODEL_CANNOT_ACCESS_GEOMETRY –

• A3D_TOOLS_COMPUTE_UV_FAILURE –

• A3D_ERROR –

• A3D_INCOMPATIBLE_FUNCTION_WITH_KEEP_PARSED_ENTITY_MODE –

• A3D_TOOLS_TESSELLATION_ISSUE –

• A3D_TOOLS_PHYSICALPROPERTIES_FAILURE –

Returns

A3D_SUCCESS in case of success or an error code

A3DStatus A3DComputeFaceArea(const A3DTopoFace *pFace, const A3DTopoContext *pBrepDataTopoContext, A3DDouble *pArea)

Function to compute the surface of the current A3DTopoFace.

The current TopoContext is needed in order to get the correct current scale.

Version

7.0

Parameters

• pFace – [in] The input A3DTopoFace.

• pBrepDataTopoContext – [in] The corresponding A3DTopoContext of the current A3DTopoBrepData who is owing the A3DTopoFace.

• pArea – [out] The surface of the A3DTopoFace in the current unit.

Return values

• A3D_SUCCESS –

• A3D_INVALID_ENTITY_TYPE –

• A3D_INVALID_ENTITY_NULL –

• A3D_INITIALIZE_NOT_CALLED –

• A3D_ERROR –

• A3D_TOOLS_TESSELLATION_ISSUE –

Returns

A3D_SUCCESS in case of success or an error code

A3DStatus A3DComputePolyBrepPhysicalProperties(const A3DRiPolyBrepModel *p, const A3DVector3dData *psScale, A3DPhysicalPropertiesData *psPhysicalPropertiesData)

Function to compute the physical properties (surface area, volume and gravity center, and since 11.2 the surfacic gravity center and the surfacic and volumic inertia matrix) of a PolyBrepModel.

An optional scale, psScale, can be used. It can be either uniform or not. Physical properties will be computed after having scaled the geometrical data in the A3DRiPolyBrepModel.

Note that since 11.2, the input psPhysicalPropertiesData structure now has a couple of input parameters with which precision can be adjusted, in addition to the new return values.

The inertia matrices are provided relative to the computed gravity centers, with respect to the global X, Y and Z directions.

Version

6.1

Parameters

• p – [in] The input poly B-rep model.

• psScale – [in] The optional scale.

• psPhysicalPropertiesData – [out] The wanted physical properties.

Return values

• A3D_SUCCESS –

• A3D_INVALID_ENTITY_TYPE –

• A3D_INVALID_ENTITY_NULL –

• A3D_INITIALIZE_NOT_CALLED –

• A3D_ERROR –

• A3D_INCOMPATIBLE_FUNCTION_WITH_KEEP_PARSED_ENTITY_MODE –

• A3D_TOOLS_TESSELLATION_ISSUE –

• A3D_TOOLS_PHYSICALPROPERTIES_FAILURE –

Returns

A3D_SUCCESS in case of success or an error code

A3DStatus A3DComputeModelFilePhysicalProperties(const A3DAsmModelFile *p, A3DPhysicalPropertiesData *psPhysicalProperties)

Function to compute the physical properties (surface area, volume and gravity center, and since 11.2 the surfacic gravity center and the surfacic and volumic inertia matrix) of a modelfile, typically an assembly.

Data is returned in the modelfile unit, without density.

Note that since 11.2, the input psPhysicalPropertiesData structure now has a couple of input parameters with which precision can be adjusted, in addition to the new return values.

The inertia matrices are provided relative to the computed gravity centers, with respect to the global X, Y and Z directions. The return values are provided in the modelfile’s unit. The surfacic quantities take into account all representation items, whereas the ones for which the volume was not computed will not be used for the volumic quantities. Note that density is not taken into account. Return values are purely volumic or surfacic. For models with a constant density different than 1 unit of weight per unit of volume, results must be adjusted: matrices must be multiplied by the density of the input CAD file.

Version

5.2

Parameters

• p – [in] The input modelfile.

• psPhysicalProperties – [out] The physical properties.

Return values

• A3D_SUCCESS –

• A3D_INITIALIZE_NOT_CALLED –

• A3D_INVALID_ENTITY_NULL –

• A3D_RI_BREPMODEL_CANNOT_ACCESS_GEOMETRY –

• A3D_TOOLS_COMPUTE_UV_FAILURE –

• A3D_ERROR –

• A3D_INCOMPATIBLE_FUNCTION_WITH_KEEP_PARSED_ENTITY_MODE –

• A3D_TOOLS_TESSELLATION_ISSUE –

• A3D_TOOLS_PHYSICALPROPERTIES_FAILURE –

Returns

A3D_SUCCESS in case of success or an error code

A3DStatus A3DSimplifyModelFileCurveAndSurfaceAsAnalytic(A3DAsmModelFile *p, double dTol)

Function to traverse the entire modelfile and simplify all curves and surfaces to analytics if possible, according to a certain tolerance.

Deprecated:

Use A3DSimplifyModelFileWithAnalytics

Version

5.2

Parameters

• p – [inout] The input modelfile.

• dTol – [in] The tolerance.

Return values

• A3D_SUCCESS –

• A3D_ERROR –

• A3D_INCOMPATIBLE_FUNCTION_WITH_KEEP_PARSED_ENTITY_MODE –

Returns

A3D_SUCCESS in case of success or an error code

A3DStatus A3DSimplifyModelFileWithAnalytics(A3DAsmModelFile *p, A3DDouble dTol, A3DUns32 uNbRecognizedType, A3DEEntityType const *pOptRecognizedType)

Function to traverse the entire modelfile and simplify all curves and surfaces to analytics if possible, according to a certain tolerance.

Recognized surface types are:Conic Surface, Cylindrical Surface, Plane Surface, Spherical Surface, Toric Surface Recognized curve types are:Linear Curve, Circular Curve If uNbRecognizedType and pOptRecognizedType are defined, A3DSimplifyModelFileWithAnalytics recognizes only the given types.

Version

7.0

Parameters

• p – [inout] The input modelfile.

• dTol – [in] The tolerance (in millimeters).

• uNbRecognizedType – [in] Size of array pOptRecognizedType.

• pOptRecognizedType – [in] Optional type of surface we want to recognize.

Return values

• A3D_SUCCESS –

• A3D_ERROR –

• A3D_INCOMPATIBLE_FUNCTION_WITH_KEEP_PARSED_ENTITY_MODE –

Returns

A3D_SUCCESS in case of success or an error code