Novell Documentation: NLM & NetWare Libraries for C

NWRegisterNCPExtension

Registers a service to be provided as an NCP extension

Local Servers:blocking
Remote Servers:N/A
NetWare Server:3.11, 3.12, 3.2, 4.x, 5.x, 6.x
Platform:NLM
Service:NCP Extension

Syntax

  #include <nlm\nwncpx.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);

Parameters

NCPExtensionName: (IN) Points to the name of an NCP Extension.
NCPExtensionHandler: (IN) Points to the function to be called when the NCP Extension calls the NWSendNCPExtensionRequest function (optional).
ConnectionEventHandler: (IN) Points to the function to be called and action to follow when a connection is freed, killed, logged out, or restarted (optional).
ReplyBufferManager: (IN) Points to a buffer manager function used to reply to NCP Extension requests (optional).
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 32-byte area that NetWare has allocated.

Return Values

The following table lists return values and descriptions.

Value	Hex	Name and description
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 NCPExtensionName parameter is longer than the 32-byte limit.

Remarks

NWRegisterNCPExtension is called by the service-providing NLM applications in conjunction with the NWDeRegisterNCPExtension function.

NCP extension names are case sensitive and must be unique. They have a maximum length of 32 bytes plus a NULL terminator.

The queryData parameter can be used by the service provider to return up to 32 bytes of information to the client and is aligned on a DWORD (32-bit) boundary. This information can then be retrieved by calling the NWGetNCPExtensionInfo (NLM) or NWScanNCPExtensions (NLM) function. The queryData parameter is also used by the registering NLM as the NCP extension handle when the NWDeRegisterNCPExtension function is called.

NOTE:The NCPExtensionHandler parameter returns a BYTE representing the value returned when the NWSendNCPExtensionRequest function is called. The extension handler can return any value other than those used by the lower-level NCP-transport services (see niterror.h). However, information is placed into the replyData parameter after the NCPExtensionHandler parameter returns SUCCESSFUL.

Other status information can be returned to the client with the extension handler. However, do not return any values (other than SUCCESSFUL) that NWRegisterNCPExtension can return. Otherwise, future versions of the OS might return values you have defined and confuse their meaning. If the extension handler always returns SUCCESSFUL and then uses a "status" field in the replyData parameter to return status information, the meaning of each return value will be clear.

If you can provide all needed information by updating the 32-byte queryData buffer, pass NULL to the NCPExtensionHandler parameter. Then call either the NWGetNCPExtensionInfo (NLM) or NWScanNCPExtensions (NLM) function to obtain information in the queryData buffer. This is a passive method of passing information. The NCP extension will not be notified that the queryData parameter was accessed.

NOTE:The NCPExtensionHandler, ConnectionEventHandler, and ReplyBufferManager parameters are function callbacks that run as OS threads. They need to have CLIB context if they are going to make calls into CLIB that need context.

The function pointed to by the NCPExtensionHandler parameter has the following parameters:

client: (IN) Points to the NCPExtensionClient structure containing the connection and task of the calling client (also used by the ReplyBufferManager parameter to associate the request with the reply notification it receives).
requestData: (IN) Points to a buffer, which might be DWORD aligned, to hold the request information.
requestDataLen: (IN) Specifies the size (in bytes) of the data in the requestData parameter.
replyData: (OUT) Points to a buffer to store the response data from the service routine if the ReplyBufferManager parameter is NULL. Otherwise, points to the address of a valid buffer, which might be DWORD aligned, that the NCP extension handler created.
replyDataLen: (IN/OUT) Inputs the maximum size (in bytes) of information that can be stored in the reply buffer. Outputs the actual number of bytes that the NCPExtensionHandler parameter stored in the reply buffer.

The function pointed to by the ConnectionEventHandler parameter has the following parameters:

connection

(IN) Specifies the connection number for any connection (NCP extension clients and others) that was logged out or cleared (optional).

eventType

(IN) Specifies the type of event that is being reported for NetWare 3.12 and higher (optional):

CONNECTION_BEING_FREED
CONNECTION_BEING_KILLED
CONNECTION_BEING_LOGGED_OUT
CONNECTION_BEING_FREED

You must decide if it is important for your service to be aware of when clients (particularly the NCP extension clients) log out or terminate a connection.

The ConnectionEventHandler parameter does not return a value.

The function pointed to by the ReplyBufferManager parameter has the following parameters:

client: (IN) Points to the 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 (optional).

Syntax

Parameters

Return Values

Remarks

See Also