NWRegisterNCPExtensionByID(3xti_ncp)


NWRegisterNCPExtensionByID -- using a specific ID, register an NCP extension with NetWare Services

Synopsis

#include <ncpx_app.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

NWRegisterNCPExtensionByID registers the NCP extension with NetWare® using a well-known ID. This ID is always associated with the application's service.

After an NCP extension has been registered, clients can access the NCP extension. The extension remains valid until the service-providing program deregisters the NCP extension.

NCPExtensionID is the ID for the NCP extension associated with your application service. Your ID must be unique and within the valid range. For more information on NCP extension Names, refer to NWRegisterNCPExtension(3xti_ncp).

NCPExtensionName is the name that the NCP extension uses as an identifier 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.

When you call NWRegisterNCPExtensionByID to register an NCP extension, three of the parameters are functions that are called as part of the Handler service. These parameters are NCPExtensionHandler, ConnectionEventHandler, and ReplyBufferManager. For a more detailed description of the parameters for the functions referenced by these pointers, see NWRegisterNCPExtension(3xti_ncp).

The function pointed to by NCPExtensionHandler is a service routine (function) that is called when the client calls the NCP extension with NWSendNCPExtensionRequest or NWSendNCPExtensionFraggedRequest.

The function pointed to by ConnectionEventHandler keeps track of when connections are freed or logged out. If keeping track of connection status is not important to you, you can pass NULL for the connection event handler when you register the NCP extension.

The function pointed to by ReplyBufferManager is used if the service-providing application wants to take care of reply buffer management for itself. Most cases do not require a reply buffer manager. If you do not need one, pass NULL for this parameter.

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

The queryData buffer is used by the service provider to return up to 32 bytes of information to the client. The pointer is also used by the registering NCPX application as the NCP extension handle, when calling NWDeRegisterNCPExtension.

Returning the contents of the update buffer to the client also provides a one-way, passive information passing scheme. 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 or NWScanNCPExtensions.

Parameters

(IN) NCPExtensionID
Gives the well-known ID for the NCP extension.

(IN) NCPExtensionName
Gives the name that identifies the NCP extension.

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

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

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

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

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

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

(OUT) queryData
Receives a pointer to a 32-byte area that the NCPX Handler library allocated. This buffer is used by the service provider to return up to 32 bytes of information to the client.

Return values

0 (0x00)
SUCCESSFUL

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 NCPExtensionName parameter was longer than the 32-byte limit

References

NWRegisterNCPExtension(3xti_ncp), NWDeRegisterNCPExtension(3xti_ncp)
30 January 1998
© 1998 The Santa Cruz Operation, Inc. All rights reserved.