# Getting Started with C API

# Prerequisites

C99 compatible compiler
The Face Verification Library shared library (.so / .dylib / .dll)

# Installation

Extract the SDK contents, include faceverifier_c.h from the include folder and link libFaceVerificationLibrary to your C project.

# Quick Start Example

#include "faceverifier_c.h"
#include <stdio.h>
#include <stdlib.h>

/* Callback for face detection */
void on_faces_detected(void* user_data, FVLFaceArray* faces, const char* error_msg) {
    if (error_msg) {
        fprintf(stderr, "Detection error: %s\n", error_msg);
        return;
    }
    printf("Detected %d face(s)\n", faces->count);

    /* Process each face... */
    for (int i = 0; i < faces->count; i++) {
        FVLBoundingBox bbox = fvl_face_bounding_box(faces->faces[i]);
        printf("  Face %d: (%d, %d, %d, %d)\n", i, bbox.x, bbox.y, bbox.width, bbox.height);
    }
}

int main() {
    char* error = NULL;

    /* Create verifier */
    FVLFaceVerifier* verifier = fvl_face_verifier_new("model/model.realZ", 0, &error);
    if (!verifier) {
        fprintf(stderr, "Failed to create verifier: %s\n", error);
        free(error);
        return 1;
    }

    /* Detect faces (async with callback) */
    FVLImageHeader header = {image_data, width, height, stride, FVLImageFormatRGB};
    fvl_face_verifier_detect_faces(verifier, &header, on_faces_detected, NULL);

    /* Clean up */
    fvl_face_verifier_free(verifier);
    return 0;
}

# Common Patterns

# Error Handling

Functions that can fail accept a char** errorMessage output parameter. On failure, the function returns NULL and sets the error message. The caller must free the error string:

char* error = NULL;
FVLFaceVerifier* verifier = fvl_face_verifier_new("model.realZ", 0, &error);
if (!verifier) {
    fprintf(stderr, "Error: %s\n", error);
    free(error);
}

Pass NULL for errorMessage if you don't need the error details.

# Memory Management

Function Returns	Must Free?	How
`fvl_face_verifier_new()`	Yes	`fvl_face_verifier_free()`
`fvl_face_new()`	Yes	`fvl_face_free()`
`fvl_face_copy()`	Yes	`fvl_face_free()`
`fvl_face_landmarks()`	Yes	`free()`
`fvl_face_verifier_get_model_name()`	Yes	`free()`
`fvl_face_verifier_get_sdk_version_string()`	Yes	`free()`
`errorMessage` output parameter	Yes	`free()`
Callback parameters (`faces`, `embedding`, `error_msg`)	No	Valid only during callback

# Callbacks

Async operations use callbacks. The result and error_msg parameters are only valid during the callback — copy any data you need to retain:

void on_embedding(void* user_data, FVLFloatArray* embedding, const char* error_msg) {
    if (error_msg) {
        /* handle error */
        return;
    }
    /* Copy embedding data if needed beyond callback lifetime */
    float* my_embedding = malloc(embedding->count * sizeof(float));
    memcpy(my_embedding, embedding->data, embedding->count * sizeof(float));
}

# Next Steps

C API Reference