## Callback functions

Callbacks are a separate type of C3D Solver API function, the
peculiarity of which is that they are called from within the C3D Solver
and can be defined on the application side. The need for such functions
arises when it is necessary to provide the solver with access to data
stored on the application side, determine the properties of geometric
objects, and also provide feedback to the solver with queries that
affect the progress of calculations. Callbacks enhance the ability to
integrate the solver with the application by providing another channel
of interaction. All functions and data types for organizing callbacks
are collected in a separate header file **gce_callback.h**.

In order for user-defined callback functions to work for a given
constraint system, they must be registered using the
`call`{#GCE\\_Register}

```cpp
GCE_result GCE_Register(GCE_system gSys, const GCE_callback_table & cbTable)
```

Input data:

-   **gSys** -- constraint system that callbacks will serve;

-   **cbTable** is a callback table that defines the following set of
    functions:

    -   **gRegister** -- a function of the
        `void (*GCE_geom_registered)(GCE_app_geom ag)` form called by
        the solver when a user geometry is registered with **gSys**
        using the GCM_Bind call.

    -   **gUnregister** -- a function of the
        `void (*GCE_geom_unregistered)(GCE_app_geom ag)` form called for
        the geometric object **ag** at the moment in time when the
        geometric solver releases the object **ag**, stopping all work
        with it. This event occurs on direct calls such as
        GCE_RemoveGeom, **GCE_RemoveSystem**, or **GCE_ClearSystem**.

    -   **abortFunc** --- function for requesting to abort calculations.
        This is a Boolean function of the form bool (\***GCE_abort**)(),
        which is called from time to time in the solver while
        GCE_Evaluate is running and stops computing if the function
        returns true. A **GCE_Evaluate** that is aborted in this way
        will return the error code **GCE_RESULT_Aborted**.

    -   **allowZeroRadius** -- a callback function of the form
        `bool (*GCE_allow_zero_radius)(GCE_app_geom ag)` that tells the
        constraint system that circle **ag** allows a solution where its
        radius is zero.

    -   **allowZeroLength** -- a callback function of the form
        `bool (*GCE_allow_zero_length)(GCE_app_geom ag)`, that tells the
        constraint system that line segment or bounded curve **ag**
        allows a solution where their length is zero. For example, a CAD
        application can use the zero-length option to prohibit a line
        segment of zero length if it represents the axis of symmetry in
        a drawing. To enforce this prohibition, the application should
        return false when allowZeroLength is called.

    -   **getLSegDirection** -- a callback function of the form
        `GCE_vec2d(*GCE_get_lseg_direction)(GCE_app_geom ag)`, that
        allows to get the direction of the line segment **ag**. It is
        designed so that the application does not forget where the
        segment L = 0 is "looking" when it needs to return its length
        again. And also to avoid the effect of "turning out" the line
        segment when participating in such constraints as "tangency" and
        "at a distance".

Return value:

-   **GCE_RESULT_Ok** if the callback table was successfully registered
    for the constraint system;

-   **GCE_RESULT_None** if callback registration fails.

***Note***

For the solver to work correctly, the **[GCE_Register](#GCE\_Register)**
call should be called once for the same constraint system, while it is
still empty, for example, immediately after GCE_CreateSystem.