Novell Documentation: NLM & NetWare Libraries for C

RegisterLibrary

Registers an NLM as a library with the NetWare® API

Local Servers:blocking
Remote Servers:N/A
Classification:3.x, 4.x, 5.x, 6.x
Service:Library

Syntax

  #include <nwlib.h>  
   
  LONG RegisterLibrary  (  
     int   (*clientCleanupFunc) (void *));

Parameters

clientCleanupFunc: (IN) Points to a function to be called whenever one of the clients of the library is terminated by either an UNLOAD command or because the NLM terminated itself by calling exit, abort, ExitThread, or so on (see "Note" below).

Return Values

This function returns a library handle or a value of 0xFFFFFFFF if an error occurs.

Remarks

If the calling library wants to support downstream clients that are coding to LibC, call register_library instead of calling RegisterLibrary.

RegisterLibrary must be called prior to any other function requiring a library handle.

NOTE:The prototype of the clientCleanupFunc indicates that it returns a value of type (int). Although NetWare currently ignores this value, clientCleanupFunc functions should always return ESUCCESS (or zero).

NOTE:It is possible to write a library NLM without using the Library functions.

For an NLM to be considered a client of a registered library by the NetWare API, the library must call SaveDataAreaPtr with a nonNULL data area pointer while the client NLM is the current NLM (this is usually done when the client makes its first call to the library). Only NLM applications that are clients of registered library NLM applications cause a client cleanup function to be called when they terminate.

NOTE:The library clean-up routines must be given CLIB context if they use NLM API functions that require context. You can set the context using SetThreadGroupID but you must set it to a thread group ID that is part of the library, since the cleanup routine is part of the library, not part of your NLM. You should save the default thread group ID when you enter your routine and restore it, using SetThreadGroupID, before you leave your routine.

Example of a Library NLM

  #include <stdio.h>  
  #include <nwconio.h>  
  #include <nwlib.h> 
    
  int   LibHandle;  
  int      threadGroupID;  
   
  /*........................*/  
  int LibCleanupFunc  
  (  
  void *data  
  )  
  {  
     int    curThreadGroupID;  
     void   *dataAreaPtr; 
    
     data = data;  
     /*...we must establish context for the thread running  
        the cleanup function...*/  
   
     curThreadGroupID = SetThreadGroupID(threadGroupID);  
     printf("Data ptr : %lX\n\n", data);  
     printf("%lX Client closed.\n\n", GetThreadID());  
   
     /*...restore the running thread’s original context...*/  
     SetThreadGroupID(curThreadGroupID);  
     return(0);  
  }  
  /*........................*/  
   
  main()  
  {  
     /*...save the thread group ID of the main lib thread group...*/  
     threadGroupID = GetThreadGroupID();  
     LibHandle = RegisterLibrary(LibCleanupFunc);  
     if (LibHandle != -1)  
        SuspendThread(GetThreadID());  
     else  
        ConsolePrintf("\n\nUnable to register library.\n\n");  
  }  
  /*........................*/

Example of a Client NLM

  #include <stdio.h>  
  #include <nwconio.h>  
  #include <nwlib.h>  
  extern   int   LibHandle;  
  /*........................*/  
  main()  
  {  
     void   *dataAreaPtr;  
     dataAreaPtr = (void *)0x11223344;  
     /*...become a client of the library...*/  
     if (SaveDataAreaPtr(LibHandle, dataAreaPtr))  
        ConsolePrintf("\n\nUnable to get data area ptr for the  
                       library.\n\n");  
     getch();  
  }  
  /*........................*/