NWRegisterNCPExtension(3nw)


NWRegisterNCPExtension -- registers service to be provided as NCP extension

Synopsis

   #include <ncpext.h> 
   int NWRegisterNCPExtension ( 
      const char    *NCPExtensionName, 
      BYTE         (*NCPExtensionHandler)( 
         NCPExtensionClient  *client, 
         void                *requestData, 
         LONG                  requestDataLen, 
         void                *replyData, 
         LONG                *replyDataLen), 
      void         (*ConnectionEventHandler)( 
         LONG                 connection, 
         LONG                 eventType) 
      void         (*ReplyBufferManager)( 
         NCPExtensionClient  *client, 
         void                *replyBuffer), 
      BYTE          majorVersion, 
      BYTE          minorVersion, 
      BYTE          revision, 
      void        **queryData); 

Description

The parameters are as follows:

NCPExtensionName
(IN) Points to the name of the NCP Extension.

NCPExtensionHandler
(IN) Points to the function that to be executed when the NCP Extension is called with NWSendNCPExtensionRequest.

ConnectionEventHandler
(IN) Points to the function that to be called when a connection is logged out or terminated on the server.

ReplyBufferManager
(IN) Points to a reply buffer manager that can be used to manage buffers used to reply to NCP Extension requests.

majorVersion
(IN) Specifies the major version number of the service provider.

minorVersion
(IN) Specifies the minor version number of the service provider.

revision
(IN) Specifies the revision number of the service provider.

queryData
(OUT) Points to a pointer to a 32-byte area that the NetWare API has allocated. This buffer can also be used by the service provider to return up to 32 bytes of information to the client. This buffer is aligned on a DWORD (32-bit) boundary.

The queryData pointer is also used by the registering NLM as the NCP extension handle, when calling NWDeRegisterNCPExtension.

Return values

0 (0x00) SUCCESSFUL The extension was found, and the non-null output parameters were filled.
5 (0x05) ENOMEM Not enough memory was available on the server to register the service.
166 (0xA6) ERR_ALREADY_IN_USE The NCP Extension name is already registered. Your service is not registered.
255 (0xFF) ERR_BAD_PARAMETER The NCP Extension name was longer than the 32-byte limit.

 
 ---------------------------------------------------------- 
| 0  |  (0x00)|  SUCCESSFUL        |  The extension was   | 
|    |        |                    |  found, and the non- | 
|    |        |                    |  null output         | 
|    |        |                    |  parameters were     | 
|    |        |                    |  filled.             | 
|----|--------|--------------------|----------------------| 
| 5  |  (0x05)|  ENOMEM            |  Not enough memory   | 
|    |        |                    |  was available on the| 
|    |        |                    |  server to register  | 
|    |        |                    |  the service.        | 
|----|--------|--------------------|----------------------| 
| 166|  (0xA6)|  ERR_ALREADY_IN_USE|  The NCP Extension   | 
|    |        |                    |  name is already     | 
|    |        |                    |  registered. Your    | 
|    |        |                    |  service is not      | 
|    |        |                    |  registered.         | 
|----|--------|--------------------|----------------------| 
| 255|  (0xFF)|  ERR_BAD_PARAMETER |  The NCP Extension   | 
|    |        |                    |  name was longer than| 
|    |        |                    |  the 32-byte limit.  | 
|----|--------|--------------------|----------------------| 

Notices

NWRegisterNCPExtension and NWDeRegisterNCPExtension are used by service providing NLM applications to register and deregister NCP extensions that clients (NLM applications and workstations) can call.

NCPExtensionName is the name the NCP extension is to be identified by in the list of NCP extensions. NCP extension names are case sensitive and must be unique. They have a maximum length of 32 bytes plus a NULL terminator. For more information about NCP extension names, refer to ``NCP extensions''.

NCPExtensionHandler is a service routine (function) that is called when the client calls the NCP extension with NWSendNCPExtensionRequest. This routine takes the following parameters:

client
(IN) Points to an NCPExtensionClient structure containing the connection and task of the calling client. The client pointer can be used by the ReplyBufferManager to associate the request with the reply notification it receives.

requestData
(IN) Points to a buffer holding the request information. This data buffer itself may or may not be DWORD aligned.

requestDataLen
(IN) Indicates the size (in bytes) of the data in the request buffer.

replyData
(OUT) {Points to a buffer where the service routine can place its response data if the ReplyBufferManager parameter of NWRegisterNCPExtension is set to NULL. If a ReplyBufferManager was specified, replyData points to the address of a pointer which your NCP extension handler sets to a valid buffer it has created. The data buffer itself may or may not be DWORD aligned.

replyDataLen
(IN/OUT) Inputs the maximum size (in bytes) of information that can be stored in the reply buffer. On output, this is the actual number of bytes that NCPExtensionHandler stored in the reply buffer.
NCPExtensionHandler returns a BYTE. This is the value returned when a client calls NWSendNCPExtensionRequest. The extension handler can return any value other than those used by the lower-level NCP-transport services (see niterror.h); however, be aware that the information that NCPExtensionHandler places in to which replyData points is returned to the client only when NCPExtensionHandler returns SUCCESSFUL (0).

Your extension handler might want to return other status information to the client, such as failure reasons. If you do this, do not use any values that have been defined to return from NWRegisterNCPExtension. The risk in returning values other than SUCCESSFUL is that future versions of the OS might return values you have defined, leaving you unsure of the return values' meanings.

A better way for your extension handler to return status information is for it to always return SUCCESSFUL and then use a ``status'' field in the buffer to which replyData points. This technique guarantees that the status information is always from your handler.

In most cases, you want to provide an NCP extension handler. However, if your service can provide all information needed by updating the 32-byte queryData buffer, you do not need an extension handler and can pass NULL for the parameter. The clients would then obtain the information in the queryData buffer by calling NWGetNCPExtensionInfo or NWScanNCPExtensions. This is a passive method of passing information. The NCP extension is not notified that an access has been made to its queryData.

ConnectionEventHandler is a function that is called when any connection is freed, killed, logged out, or restarted. This function needs to determine if any action must be taken because of the connection being logged out or cleared. It has the following parameters:

connection
(IN) Indicates the number of the connection that was logged out or cleared. (This notification is for all connections that are logged out or cleared. The connection information is not always about an NCP extension client.) If your service does not need to handle logged out or terminated connections, pass NULL for this parameter.

eventType
(IN) Indicates the type of event that is being reported. The types are CONNECTION_BEING_FREED, CONNECTION_BEING_KILLED, CONNECTION_BEING_LOGGED_OUT, and CONNECTION_BEING_FREED. The eventType parameter is new with the NetWare 4.0(TM) OS and is compatible for use with NetWare 3.12 but is not valid for NetWare 3.11. See ``NCP extensions''.
You must decide if it is important for your service to be aware of when clients (particularly the NCP extension's clients) log out or terminate their connections. If your service does not need to handle logged out or terminated connections, pass NULL for this parameter.

ConnectionEventHandler does not return a value.

ReplyBufferManager is a function that is used if the service-providing NLM is written to take care of reply buffer management for itself. This function takes the following parameters:

client
(IN) Points to an NCPExtensionClient structure containing the connection and task of the calling client.

replyBuffer
(IN) Points to a buffer whose information has been returned to the client.
In most cases, you do not use a reply buffer manager. If you do not need one, pass NULL for this parameter.


NOTE: NCPExtHandler, ConDownHandler, and ReplyBufferManager are callbacks, and are running as OS threads. They need to have CLIB context if they are going to make NetWare API calls that need context. For information about the context issues, refer to ``NCP extensions''.

The majorVersion, minorVersion, and revision parameters allow you to identify the version and revision of your service provider.

The queryData parameter is a pointer to a 32-byte buffer that the NetWare API has allocated. Your service provider can use the buffer to supply periodic update information to its clients. This information can then be retrieved by calling NWGetNCPExtensionInfo or NWScanNCPExtensions. The data buffer itself is DWORD aligned.

The queryData pointer is also used as a handle when deregistering the NCP extension with NWDeRegisterNCPExtension.

Services

NCP Extension

Example

/* echoserv.c -- The server side of the ECHO SERVER NCP extension*/ 
#include <ncpext.h> 
#include <stdio.h> 
#include <advanced.h> 
#include <process.h> 
#include <conio.h> 
#include <errno.h> 
BYTE EchoServer(NCPExtensionClient *client, BYTE *requestData, LONG 
   requestDataLen, BYTE *replyData, LONG *replyDataLen); 
void EchoServerConnDownHandler(LONG connection); 
int myThreadGroupID; 

struct queryDataStruct { LONG CharsEchoed; LONG unused[7]; } *queryData;

void main(void) { myThreadGroupID = GetThreadGroupID(); SetThreadContextSpecifier(GetThreadID(), NO_CONTEXT); NWRegisterNCPExtension("ECHO SERVER", EchoServer, EchoServerConnDownHandler, NULL, 1, 0, 0, &queryData); queryData->CharsEchoed = 0; printf("Press any key to unload echo server.\n"); getch(); NWDeRegisterNCPExtension(queryData); }

BYTE EchoServer(NCPExtensionClient *client, BYTE *requestData, LONG requestDataLen, BYTE *replyData, LONG *replyDataLen) { int savedThreadGroupID; savedThreadGroupID = GetThreadGroupID(); SetThreadGroupID(myThreadGroupID); /* echo character*/ putchar(*(char *)requestData); *replyDataLen = 1; /* return echoed character*/ *replyData = *requestData; queryData->CharsEchoed++; SetThreadGroupID(savedThreadGroupID); return 0; }

void EchoServerConnEventHandler(LONG connection, LONG eventType) { ConsolePrintf("\nECHO SERVER notified of connection %d logged out or returned\n", connection); }

References

NWDeRegisterNCPExtension(3nw), NWGetNCPExtensionInfo(3nw), NWScanNCPExtensions(3nw), NWSendNCPExtensionRequest(3nw), NWRegisterNCPExtensionByID(3nw)


30 January 1998
© 1998 The Santa Cruz Operation, Inc. All rights reserved.