4.3 Client helper library

Let us build a client library that encapsulates calls to the hello world server. The library will be made available for other packages by BID, so any package can use the library for easy communicating with the hello world server.

The functions exported by the library will be declared as prototypes in an include file. The include file will also be made available for other packages by BID. Let us create the include file first. Switch to the $(PKGDIR)/include/ directory and create the new file hiworld.h:

hiworld/include/hiworld.h

#ifndef __HIWORLD_INCLUDE_HIWORLD_H_
#define __HIWORLD_INCLUDE_HIWORLD_H_
#include <l4/hiworld/hiworld-client.h>

#define hiworld_name "hiworld"
int hiworld_print(void);
int hiworld_count(void);

#endif

The prepared makefile installs all include files in the directory tree, so that other packages can use them. Our newly created file will be accessed with #include <l4/hiworld/hiworld.h> later:

~/src/l4/pkg/hiworld/include> make O=/path/to/build

Client libraries are typically build in the $(PKGDIR)/lib/ directory of a package. Like in the server directory, there is a src/ subdirectory. Switch into it and create the new file encap.c containing the encapsulation code:

hiworld/lib/src/encap.c

#include <l4/names/libnames.h>
#include <l4/env/errno.h>
#include <l4/sys/consts.h>
#include <l4/hiworld/hiworld.h>

static l4_threadid_t server_id = L4_INVALID_ID;
static CORBA_Object server = &server_id;
            
//! Request netserver id at nameserver
static int check_server(void){
    if (l4_is_invalid_id(server_id)){
        if (!names_waitfor_name("hiworld",&server_id,10000)) return 1;
    }
    return 0;
}

//! print the string
int hiworld_print(void){
    CORBA_Environment env = dice_default_environment;

    if (check_server()) return -L4_EINVAL;
    hi_print_call(server, &env);
    return -env._p.ipc_error;
}
//! get the string
int hiworld_count(void){
    CORBA_Environment env = dice_default_environment;
    int count;

    if (check_server()) return -L4_EINVAL;
    count=hi_count_call(server, &env);
    if(!env._p.ipc_error) return count;
    return -env._p.ipc_error;
}

The makefile in this directory is already prepared to create libraries. We still have to specify which files go into it. BID also knows about generated IDL client files, the according make variable is $(CLIENTIDL):

hiworld/lib/src/Makefile

PKGDIR          ?= ../..
L4DIR           ?= $(PKGDIR)/../..

TARGET          = lib$(PKGNAME).a
SRC_C           = encap.c
CLIENTIDL       = hiworld.idl

include $(L4DIR)/mk/lib.mk

Finally, build the library and install it, so others can use it:

~/src/l4/pkg/hiworld/lib/src> make O=/path/to/build