== Sample code ==


== Section 1: Examples using only the core functions ==

==== Example 1.1: Creating and freeing a port ====
{{{
#include <stdlib.h> // for malloc(), free()
#include <string.h> // for memset(), memcpy()
#include "livido.h"
#include "livido.c"

void *livido_malloc_f (size_t size) {return malloc(size);}
void livido_free_f (void *ptr) {free(ptr);}
void *livido_memset_f (void *s, int c, size_t n) {return memset(s,c,n);}
void *livido_memcpy_f (void *dest, const void *src, size_t n) {return memcpy(dest,src,n);}

int main (void) {
  livido_port_t *filter=livido_port_new (LIVIDO_PORT_TYPE_FILTER_CLASS);
  if (filter!=NULL) livido_port_free (filter);
  return 1;
}
}}}


==== Example 1.2: Creating a port, setting and reading an int, and freeing the port ====
{{{
#include <stdlib.h> // for malloc(), free()
#include <string.h> // for memset(), memcpy()
#include <stdio.h>
#include "livido.h"
#include "livido.c"

void *livido_malloc_f (size_t size) {return malloc(size);}
void livido_free_f (void *ptr) {free(ptr);}
void *livido_memset_f (void *s, int c, size_t n) {return memset(s,c,n);}
void *livido_memcpy_f (void *dest, const void *src, size_t n) {return memcpy(dest,src,n);}

int main (void) {
  int in_int=55;
  int out_int;
  livido_port_t *filter=livido_port_new (LIVIDO_PORT_TYPE_FILTER_CLASS);

  livido_property_set (filter,"test",LIVIDO_ATOM_TYPE_INT,1,&in_int);
  livido_property_get (filter,"test",0,&out_int);

  printf ("test is %d\n",out_int);

  livido_port_free (filter);
  return 1;
}
}}}


==== Example 1.3: Creating a port, setting and retrieving a UTF-8 string, and freeing the port ====
{{{
#include <stdlib.h> // for malloc(), free()
#include <string.h> // for memset(), memcpy()
#include <stdio.h>
#include "livido.h"
#include "livido.c"

void *livido_malloc_f (size_t size) {return malloc(size);}
void livido_free_f (void *ptr) {free(ptr);}
void *livido_memset_f (void *s, int c, size_t n) {return memset(s,c,n);}
void *livido_memcpy_f (void *dest, const void *src, size_t n) {return memcpy(dest,src,n);}

int main (void) {
  char *in_string="LiViDO Test";
  char *out_string;
  livido_port_t *filter=livido_port_new (LIVIDO_PORT_TYPE_FILTER_CLASS);

  livido_property_set (filter,"name",LIVIDO_ATOM_TYPE_STRING,1,&in_string,NULL);

/* don't forget to add one byte for the terminating NULL */
  out_string=(char *)malloc(livido_property_element_size(info,"name",0)+1);
  livido_property_get (filter,"name",0,&out_string);
  printf ("name is %s\n",out_string);

  free (out_string);

  livido_port_free (filter);
  return 1;
}
}}}

==== Example 1.4: Storing a reference to pointer type, retrieving and copying ====
{{{
#include <stdlib.h> // for malloc(), free()
#include <string.h> // for memset(), memcpy()
#include <stdio.h>
#include "livido.h"
#include "livido.c"

void *livido_malloc_f (size_t size) {return malloc(size);}
void livido_free_f (void *ptr) {free(ptr);}
void *livido_memset_f (void *s, int c, size_t n) {return memset(s,c,n);}
void *livido_memcpy_f (void *dest, const void *src, size_t n) {return memcpy(dest,src,n);}

int main (void) {
  void *source_blob=malloc(1024);
  void *blob_ptr,*dest_blob;

  livido_port_t *filter=livido_port_new (LIVIDO_PORT_TYPE_FILTER_CLASS);

  livido_property_set (filter,"internal",LIVIDO_ATOM_TYPE_VOIDPTR,1,&source_blob);
  livido_property_get (filter,"internal",0,&blob_ptr);

  if (blob_ptr==source_blob) printf ("pointer was stored correctly\n");
  printf ("stored a pointer to a memory block %p\n",blob_ptr);

  free (source_blob);
  free (dest_blob);

  livido_port_free (filter);
  return 1;
}
}}}

==== Example 1.5: Setting and reading a double array ====
{{{
#include <stdlib.h> // for malloc(), free()
#include <string.h> // for memset(), memcpy()
#include <stdio.h>
#include "livido.h"
#include "livido.c"

void *livido_malloc_f (size_t size) {return malloc(size);}
void livido_free_f (void *ptr) {free(ptr);}
void *livido_memset_f (void *s, int c, size_t n) {return memset(s,c,n);}
void *livido_memcpy_f (void *dest, const void *src, size_t n) {return memcpy(dest,src,n);}

int main (void) {
  double in_doubles[3]={25.31,19.76,7.65};
  double out_doubles;
  int num_elements,i;

  livido_port_t *filter=livido_port_new (LIVIDO_PORT_TYPE_FILTER_CLASS);
  livido_property_set (filter,"double array",LIVIDO_ATOM_TYPE_DOUBLE,3,&in_doubles);

  num_elements=livido_property_num_elements (filter,"double array");
  printf ("stored an array with %d elements\n",num_elements);

  for (i=0;i<num_elements;i++) {
    livido_property_get (filter,"double array",i,&out_doubles);
    printf ("element %d is %.2f\n",i,out_doubles);
  }

  livido_port_free (filter);
  return 1;
}
}}}

==== Example 1.6: Setting and reading a pointer array ====
{{{
#include <stdlib.h> // for malloc(), free()
#include <string.h> // for memset(), memcpy()
#include <stdio.h>
#include "livido.h"
#include "livido.c"

void *livido_malloc_f (size_t size) {return malloc(size);}
void livido_free_f (void *ptr) {free(ptr);}
void *livido_memset_f (void *s, int c, size_t n) {return memset(s,c,n);}
void *livido_memcpy_f (void *dest, const void *src, size_t n) {return memcpy(dest,src,n);}

int main (void) {
  void *in_array[3];
  void *out_blob;
  int num_elements,i;
  size_t sizes[3]={128,256,1024};

  livido_port_t *filter=livido_port_new (LIVIDO_PORT_TYPE_FILTER_CLASS);

  in_array[0]=malloc(sizes[0]);
  in_array[1]=malloc(sizes[1]);
  in_array[2]=malloc(sizes[2]);

  printf ("ptrs are: %p %p %p\n",in_array[0],in_array[1],in_array[2]);

  livido_property_set (filter,"void array",LIVIDO_ATOM_TYPE_VOIDPTR,3,&in_array,sizes);

  num_elements=livido_property_num_elements (filter,"void array");
  printf ("stored an array with %d elements\n",num_elements);

  for (i=0;i<num_elements;i++) {
    livido_property_get (filter,"void array",i,&out_blob);
    printf ("element %d is %p\n",i,out_blob);
  }

  free (in_array[0]);
  free (in_array[1]);
  free (in_array[2]);
  livido_port_free (filter);
  return 1;
}
}}}


==== Example 1.7: Setting the type of a property without setting its value ====
{{{
#include <stdlib.h> // for malloc(), free()
#include <string.h> // for memset(), memcpy()
#include <stdio.h>
#include "livido.h"
#include "livido.c"

void *livido_malloc_f (size_t size) {return malloc(size);}
void livido_free_f (void *ptr) {free(ptr);}
void *livido_memset_f (void *s, int c, size_t n) {return memset(s,c,n);}
void *livido_memcpy_f (void *dest, const void *src, size_t n) {return memcpy(dest,src,n);}

int main (void) {
  int type;
  livido_port_t *filter=livido_port_new (LIVIDO_PORT_TYPE_FILTER_CLASS);

  /* set just the property type, without setting a value */
  livido_property_set (filter,"test",LIVIDO_ATOM_TYPE_INT,0,NULL);

  type=livido_property_atom_type (filter,"test");

  if (type==LIVIDO_ATOM_TYPE_INT) printf ("\"test\" is an int property\n");

  livido_port_free (filter);
  return 1;
}
}}}

==== Example 1.8: Setting the type of a property, then trying to change it ====
{{{
#include <stdlib.h> // for malloc(), free()
#include <string.h> // for memset(), memcpy()
#include <stdio.h>
#include "livido.h"
#include "livido.c"

void *livido_malloc_f (size_t size) {return malloc(size);}
void livido_free_f (void *ptr) {free(ptr);}
void *livido_memset_f (void *s, int c, size_t n) {return memset(s,c,n);}
void *livido_memcpy_f (void *dest, const void *src, size_t n) {return memcpy(dest,src,n);}

int main (void) {
  int inint=5;
  int outint;
  int type;
  double mydouble=7.6;
  int error;
  livido_port_t *filter=livido_port_new (LIVIDO_PORT_TYPE_FILTER_INFO);

  /* make "test" an int property */
  livido_property_set (filter,"test",LIVIDO_ATOM_TYPE_INT,1,&inint);
  type=livido_property_atom_type (filter,"test");
  livido_property_get (filter,"test",0,&outint);

  if (type==LIVIDO_ATOM_TYPE_INT) printf ("\"test\" is an int property, its value is %d\n",outint);

  /* now we try to set a double in it, we should get an error */
  error=livido_property_set (filter,"test",LIVIDO_ATOM_TYPE_DOUBLE,1,&mydouble);

  printf ("error was %d\n",error);
  if (error==LIVIDO_ERROR_WRONG_ATOM_TYPE) printf ("The type could not be changed !\n");

  type=livido_property_atom_type (filter,"test");
  livido_property_get (filter,"test",0,&outint);

  if (type==LIVIDO_ATOM_TYPE_INT) printf ("\"test\" is still an int property, its value is %d\n",outint);

  livido_port_free (filter);
  return 1;
}
}}}

==== Example 1.9 setting a property readonly ====
{{{
#include <stdlib.h> // for malloc(), free()
#include <string.h> // for memset(), memcpy()
#include <stdio.h>
#include "livido.h"
#include "livido.c"

void *livido_malloc_f (size_t size) {return malloc(size);}
void livido_free_f (void *ptr) {free(ptr);}
void *livido_memset_f (void *s, int c, size_t n) {return memset(s,c,n);}
void *livido_memcpy_f (void *dest, const void *src, size_t n) {return memcpy(dest,src,n);}

int main (void) {

  int inint=5;
  int outint;
  int error;
  int is_rdonly;
  livido_port_t *filter=livido_port_new (LIVIDO_PORT_TYPE_FILTER_CLASS);

  /* make "test" an int property */
  livido_property_set (filter,"test",LIVIDO_ATOM_TYPE_INT,1,&inint);
  livido_property_get (filter,"test",0,&outint);
  is_rdonly=livido_property_get_readonly (filter,"test");

  printf ("The value of \"test\" is %d, readonly state is %d\n",outint,is_rdonly);
  
  /* now we set it readonly */
  livido_property_set_readonly (filter, "test");

  inint=7;

  /* now we try to change the value, we should get an error */
  error=livido_property_set (filter,"test",LIVIDO_ATOM_TYPE_INT,1,&inint);
  if (error==LIVIDO_ERROR_PROPERTY_READONLY) printf ("The property is readonly !\n");

  livido_property_get (filter,"test",0,&outint);
  is_rdonly=livido_property_get_readonly (filter,"test");
  printf ("The value of \"test\" is %d, readonly state is %d\n",outint,is_rdonly);

  livido_port_free (filter);
  return 1;
}
}}}

==== Example 1.10: setting all mandatory properties for an "index" parameter template, then lisiting its properties ====
{{{
#include <stdlib.h> // for malloc(), free()
#include <string.h> // for memset(), memcpy()
#include <stdio.h>
#include "livido.h"
#include "livido.c"

void *livido_malloc_f (size_t size) {return malloc(size);}
void livido_free_f (void *ptr) {free(ptr);}
void *livido_memset_f (void *s, int c, size_t n) {return memset(s,c,n);}
void *livido_memcpy_f (void *dest, const void *src, size_t n) {return memcpy(dest,src,n);}

int main (void) {
  char *name="Parameter 1";
  char *kind="INDEX";
  int default=100;
  int min=0;
  int max=255;
  int i;
  char **prop_list;
  livido_port_t *param=livido_port_new (LIVIDO_PORT_TYPE_PARAMETER_TEMPLATE);

  /* set all of the mandatory properties */
  livido_property_set (param,"kind",LIVIDO_ATOM_TYPE_STRING,1,&kind);
  livido_property_set (param,"name",LIVIDO_ATOM_TYPE_STRING,1,&name);
  livido_property_set (param,"default",LIVIDO_ATOM_TYPE_INT,1,&default);
  livido_property_set (param,"min",LIVIDO_ATOM_TYPE_INT,1,&min);
  livido_property_set (param,"max",LIVIDO_ATOM_TYPE_INT,1,&max);

  /* now list the properties */
  prop_list=livido_list_properties (param);

  if (prop_list!=NULL) {
    for (i=0;prop_list[i]!=NULL;i++) {
      printf ("Property %d is called \"%s\"\n",i,prop_list[i]);
      free (prop_list[i]);
    }
    free (prop_list);
  }

  livido_port_free (param);
  return 1;
}
}}}

== Section 2: Examples using the livido-utility functions ==

==== Example 2.1: Creating and freeing a port, setting and reading an int property, checking if properties exist ====
{{{
#include <stdlib.h> // for malloc(), free()
#include <string.h> // for memset(), memcpy()
#include <stdio.h>

#include "livido.h"
#include "livido.c"
#include "livido-utils.c"

void *livido_malloc_f (size_t size) {return malloc(size);}
void livido_free_f (void *ptr) {free(ptr);}
void *livido_memset_f (void *s, int c, size_t n) {return memset(s,c,n);}
void *livido_memcpy_f (void *dest, const void *src, size_t n) {return memcpy(dest,src,n);}

int main (void) {
  int in_int=55;
  int out_int;
  int error;

  livido_port_t *filter=livido_port_new (LIVIDO_PORT_TYPE_FILTER_CLASS);

  livido_set_int_value (filter,"test",in_int);
  if (livido_has_property (filter,"test")) printf ("filter has property \"test\"\n");

  out_int=livido_get_int_value (filter,"test",&error);

  printf ("test is %d\n",out_int);

  if (!livido_has_property (filter,"test2")) printf ("filter does not have property \"test2\"\n");

  livido_port_free (filter);
  return 1;
}
}}}

==== Example 2.2: Creating and freeing a port, setting and reading a string property ====
{{{
#include <stdlib.h> // for malloc(), free()
#include <string.h> // for memset(), memcpy()
#include <stdio.h>

#include "livido.h"
#include "livido.c"
#include "livido-utils.c"

void *livido_malloc_f (size_t size) {return malloc(size);}
void livido_free_f (void *ptr) {free(ptr);}
void *livido_memset_f (void *s, int c, size_t n) {return memset(s,c,n);}
void *livido_memcpy_f (void *dest, const void *src, size_t n) {return memcpy(dest,src,n);}

int main (void) {
  char *in_string="LiViDO test";
  char *out_string;
  int error;

  livido_port_t *filter=livido_port_new (LIVIDO_PORT_TYPE_FILTER_CLASS);

  livido_set_string_value (filter,"test",in_string);

  out_string=livido_get_string_value (filter,"test",&error);

  printf ("\"test\" is \"%s\"\n",out_string);

  free (out_string);

  livido_port_free (filter);
  return 1;
}
}}}

==== Example 2.3: Creating and freeing a port, setting and reading a voidptr property ====
{{{
#include <stdlib.h> // for malloc(), free()
#include <string.h> // for memset(), memcpy()
#include <stdio.h>

#include "livido.h"
#include "livido.c"
#include "livido-utils.c"

void *livido_malloc_f (size_t size) {return malloc(size);}
void livido_free_f (void *ptr) {free(ptr);}
void *livido_memset_f (void *s, int c, size_t n) {return memset(s,c,n);}
void *livido_memcpy_f (void *dest, const void *src, size_t n) {return memcpy(dest,src,n);}

int main (void) {
  void *in_voidptr=malloc(1024);
  void *out_voidptr;
  int error;

  livido_port_t *filter=livido_port_new (LIVIDO_PORT_TYPE_FILTER_CLASS);

  livido_set_voidptr_value (filter,"test",in_voidptr);
  out_voidptr=livido_get_voidptr_value (filter,"test",&error);

  printf ("\"test\" is %p, in ptr was %p\n",out_voidptr,in_voidptr);

  free (in_voidptr);

  livido_port_free (info);
  return 1;
}
}}}

==== Example 2.4: Creating and freeing a port, setting and reading a double array ====
{{{
#include <stdlib.h> // for malloc(), free()
#include <string.h> // for memset(), memcpy()
#include <stdio.h>

#include "livido.h"
#include "livido.c"
#include "livido-utils.c"

void *livido_malloc_f (size_t size) {return malloc(size);}
void livido_free_f (void *ptr) {free(ptr);}
void *livido_memset_f (void *s, int c, size_t n) {return memset(s,c,n);}
void *livido_memcpy_f (void *dest, const void *src, size_t n) {return memcpy(dest,src,n);}

int main (void) {
  float in_doubles[]={48.1,42.9};
  float *out_doubles;
  int error;

  livido_port_t *filter=livido_port_new (LIVIDO_PORT_TYPE_FILTER_CLASS);

  livido_set_double_array (filter,"test",2,in_doubles);
  out_doubles=livido_get_double_array (filter,"test",&error);

  printf ("\"test\" is %.2f and %.2f\n",out_doubles[0],out_doubles[1]);

  free (out_doubles);

  livido_port_free (filter);
  return 1;
}
}}}

==== Example 2.5: Creating and freeing a port, setting and reading a string array ====
{{{
#include <stdlib.h> // for malloc(), free()
#include <string.h> // for memset(), memcpy()
#include <stdio.h>

#include "livido.h"
#include "livido.c"
#include "livido-utils.c"

void *livido_malloc_f (size_t size) {return malloc(size);}
void livido_free_f (void *ptr) {free(ptr);}
void *livido_memset_f (void *s, int c, size_t n) {return memset(s,c,n);}
void *livido_memcpy_f (void *dest, const void *src, size_t n) {return memcpy(dest,src,n);}

int main (void) {
  char *in_strings[]={"test string 1","test string 2"};
  char **out_strings;
  int error;

  livido_port_t *filter=livido_port_new (LIVIDO_PORT_TYPE_INFO);

  livido_set_string_array (filter,"test",2,in_strings);

  out_strings=livido_get_string_array (filter,"test",&error);

  printf ("\"test\" is %s and %s\n",out_strings[0],out_strings[1]);

  free (out_strings[0]);
  free (out_strings[1]);
  free (out_strings);

  livido_port_free (filter);
  return 1;
}
}}}

==== Example 2.6: Creating and freeing a port, setting and reading a voidptr array ====
{{{
#include <stdlib.h> // for malloc(), free()
#include <string.h> // for memset(), memcpy()
#include <stdio.h>

#include "livido.h"
#include "livido.c"
#include "livido-utils.c"

void *livido_malloc_f (size_t size) {return malloc(size);}
void livido_free_f (void *ptr) {free(ptr);}
void *livido_memset_f (void *s, int c, size_t n) {return memset(s,c,n);}
void *livido_memcpy_f (void *dest, const void *src, size_t n) {return memcpy(dest,src,n);}

int main (void) {
  void *in_voids[2];
  void **out_voids;
  size_t in_sizes[2]={1024,256};
  int error;

  livido_port_t *filter=livido_port_new (LIVIDO_PORT_TYPE_FILTER_CLASS);

  in_voids[0]=malloc(in_sizes[0]);
  in_voids[1]=malloc(in_sizes[1]);

  livido_set_voidptr_array (filter,"test",2,in_voids);

/* warning, out_voids are reference only */
  out_voids=livido_get_voidptr_array (filter,"test",&error);

  printf ("\"test\" is %p and %p, original was %p and %p\n",out_voids[0],out_voids[1],in_voids[0],in_voids[1]);

  free (out_voids);

  livido_port_free (filter);
  return 1;
}
}}}

==== Example 2.7: Creating and freeing an INDEX parameter template, setting all the mandatory properties, setting readonly and listing them ====
{{{
#include <stdlib.h> // for malloc(), free()
#include <string.h> // for memset(), memcpy()
#include <stdio.h>
#include "livido.h"
#include "livido.c"
#include "livido-utils.c"

void *livido_malloc_f (size_t size) {return malloc(size);}
void livido_free_f (void *ptr) {free(ptr);}
void *livido_memset_f (void *s, int c, size_t n) {return memset(s,c,n);}
void *livido_memcpy_f (void *dest, const void *src, size_t n) {return memcpy(dest,src,n);}

int main (void) {
  int i;
  char **prop_list;
  livido_port_t *param=livido_port_new (LIVIDO_PORT_TYPE_PARAMETER);

  /* set all of the mandatory properties */
  livido_set_int_value (param,"kind","INDEX");
  livido_set_string_value (param,"name","Parameter1");
  livido_set_int_value (param,"default",100);
  livido_set_int_value (param,"min",0);
  livido_set_int_value (param,"max",255);

  /* now list the properties */
  prop_list=livido_list_properties (param);

  if (prop_list!=NULL) {
    for (i=0;prop_list[i]!=NULL;i++) {
      printf ("Property %d is called \"%s\"\n",i,prop_list[i]);
      livido_property_set_readonly (param,prop_list[i]);
      free (prop_list[i]);
    }
    free (prop_list);
  }

  livido_port_free (param);
  return 1;
}
}}}