<commit_before>sandscript-library-interface
============================

This provides the header files for interfacing Sandvine's SandScript Policy
Engine to arbitrary external shared libraries.

# The Public Interfaces

The SandScript Policy Engine will `dlopen()` the library and seek these
symbols:
 - `GetManifest`
 - `GetEventManifest`

These are both functions. You may implement one or both of these.
 
GetManifest must be a symbol of type `psl_GetManifest`, specifically a function
that returns the manifest of all functions in the library. You will need to
implement this if you want to extend SandScript with **functions** a SandScript
author can call.

GetEventManifest must be a symbol of type `psl_GetEventManifest`, a function
that returns the manifest of all of the events in the library.  You will need
to implement this if you want to extend SandScript to **raise events** that can be
handled in SandScript.

The library developer's primary role is to fill in the manifests with all of
the information to describe the functions and events provided by the shared
library. Please refer to the header files for more information:
 - `sharedLibTypes.h` -- common data types
 - `sharedLibManifest.h` -- for declaring functions
 - `sharedLibEvents.h` -- for declaring events

# Doxygen

The shared library interface is documented using doxygen, and a doxygen
configuration file is provided. The following command will create html
documentation in a sub-folder `documentation`.

    doxygen doxygen.cfg

# Compiling

You are building a shared library, so (assuming you are using gcc) it must be
linked with `-shared` and `-fPIC`. We also recommend turning on all warnings

    gcc -fPIC -Wall -shared -o my_shared_lib.so source1.c source2.c ...

Deploy the shared library in `/usr/local/sandvine/loadable/` to be picked up
the next time the policy engine is started.

# Sanity-Checking

To 'test' your library, there is a simple tool that will open your shared<commit_msg>Add note on naming fields and functions<commit_after>sandscript-library-interface
============================

This provides the header files for interfacing Sandvine's SandScript Policy
Engine to arbitrary external shared libraries.

# The Public Interfaces

The SandScript Policy Engine will `dlopen()` the library and seek these
symbols:
 - `GetManifest`
 - `GetEventManifest`

These are both functions. You may implement one or both of these.
 
GetManifest must be a symbol of type `psl_GetManifest`, specifically a function
that returns the manifest of all functions in the library. You will need to
implement this if you want to extend SandScript with **functions** a SandScript
author can call.

GetEventManifest must be a symbol of type `psl_GetEventManifest`, a function
that returns the manifest of all of the events in the library.  You will need
to implement this if you want to extend SandScript to **raise events** that can be
handled in SandScript.

The library developer's primary role is to fill in the manifests with all of
the information to describe the functions and events provided by the shared
library. Please refer to the header files for more information:
 - `sharedLibTypes.h` -- common data types
 - `sharedLibManifest.h` -- for declaring functions
 - `sharedLibEvents.h` -- for declaring events

# Naming Functions and Fields

When you extend the Policy Engine, you want to avoid overlap with any other
libraries or built-in subsystems. For this reason, we recommend the following
naming conventions:
 - choose a name for the subsystem (E.g., "Foo")
 - all functions begin with the subsystem name (E.g., "Foo.Func()")
 - choose a name for each event type (E.g., "Foo.Event1", "Foo.Event2")
 - all fields begin with the event prefix the belong to (E.g.,
   "Foo.Event1.Field1")

# Doxygen

The shared library interface is documented using doxygen, and a doxygen
configuration file is provided. The following command will create html
documentation in a sub-folder `documentation`.

    doxygen doxygen.cfg

# Compiling

You are building a shared library, so (assuming you are using gcc) it must be
linked with `-shared` and `-fPIC`. We also recommend turning on all warnings

    gcc -fPIC -Wall -shared -o my_shared_lib.so source1.c source2.c ...

Deploy the shared library in `/usr/local/sandvine/loadable/` to be picked up
the next time the policy engine is started.

# Sanity-Checking

To 'test' your library, there is a simple tool that will open your shared
{'fraction_non_alphanumeric': 0.06884219937416182, 'fraction_numerical': 0.001788109074653554, 'mean_word_length': 4.302132701421801, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2779649', 'n_tokens_mistral': 1179, 'n_tokens_neox': 1142, 'n_words': 625}