NWRegisterNCPExtensionByID(3nw)


NWRegisterNCPExtensionByID -- registers service to be provided as NCP Extension

Synopsis

   #include <ncpext.h> 
   

int NWRegisterNCPExtensionByID ( LONG NCPExtensionID, const char *NCPExtensionName, BYTE (*NCPExtensionHandler)( NCPExtensionClient *NCPExtensionClient, void *requestData, LONG requestDataLen, void *replyData, LONG *replyDataLen), void (*ConnectionEventHandler)( LONG connection, LONG eventType) void (*ReplyBufferManager)( NCPExtensionClient *NCPExtensionClient, void *replyBuffer), BYTE majorVersion, BYTE minorVersion, BYTE revision, void **queryData);

Description

The parameters are as follows:

NCPExtensionID
(IN) Specifies the ID for the NCP Extension, a specific ID to be associated with your service. This ID is assigned by Developer Support.

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

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

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

ReplyBufferManager
(IN) Specifies 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. The queryData pointer is used by the registering NLM as the NCP Extension handle, when calling NWDeRegisterNCPExtension. 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.

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.
251 (0xFB) ERR_UNKNOWN_REQUEST The request was made on a server version that does not support this function.
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.         | 
|----|--------|---------------------|----------------------| 
| 251|  (0xFB)|  ERR_UNKNOWN_REQUEST|  The request was made| 
|    |        |                     |  on a server version | 
|    |        |                     |  that does not       | 
|    |        |                     |  support this        | 
|    |        |                     |  function.           | 
|----|--------|---------------------|----------------------| 
| 255|  (0xFF)|  ERR_BAD_PARAMETER  |  The NCP Extension   | 
|    |        |                     |  name was longer than| 
|    |        |                     |  the 32-byte limit.  | 
|----|--------|---------------------|----------------------| 

Notices

NWRegisterNCPExtension, NWRegisterNCPExtensionByID, 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 that 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) to be called when the NCP Extension is called by the client with NWSendNCPExtensionRequest or NWSendNCPExtensionFraggedRequest.

ConnectionEventHandler is a function to be 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.

ReplyBufferManager is a function to be used if the service-providing NLM wants to take care of reply buffer management for itself.

For an explanation of the NCPExtensionHandler, ConnectionEventHandler, and ReplyBufferManager parameters and issues associated with them (such as using NULL for these parameters), see NWRegisterNCPExtension(3nw).

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

The queryData parameter points to 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 with a call to NWGetNCPExtensionInfo (NLM), NWGetNCPExtensionInfoByID, or NWScanNCPExtensions.

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


NOTE: The functions registered as NCPExtensionHandler, ConnectionEventHandler, and ReplyBufferManager are scheduled as callbacks and need to be given CLIB context if they are to the NetWare API functions. This context issue is discussed in ``NCP extensions''.

Services

NCP Extension

References

NWDeRegisterNCPExtension(3nw), NWRegisterNCPExtension(3nw)


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