NWRegisterNCPExtension(3xti_ncp)

NWRegisterNCPExtension -- using a specific name, register an NCP extension with NetWare Services

Synopsis

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

NWRegisterNCPExtension registers the NCP extension with NetWare^® Services by using the name of the NCP extension associated with the application service. This returns a dynamic ID that is valid until the service providing the Handler is terminated.

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.

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 NWRegisterNCPExtension 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.

NCPExtensionHandler points to a service routine (function) that is called when the client uses NWSendNCPExtensionRequest to call the NCP extension. In most cases, you want to provide an NCPX Handler. However, if your service can provide all information needed by updating the 32-byte queryData buffer, you do not need an NCPX 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.

The NCPExtensionHandler routine takes the following parameters:

(IN) client

A pointer 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.

typedef struct { 
    LONG connection; 
    LONG task; 
} NCPExtensionClient;

(IN) requestData

A pointer to a buffer holding the request information.

(IN) requestDataLen

The size (in bytes) of the data in the request buffer.

(OUT) replyData

If the ReplyBufferManager parameter of NWRegisterNCPExtension is set to NULL, this is a pointer to a buffer where the service routine can place its response data.

If a ReplyBufferManager was specified, this parameter points to the address of a pointer which the NCPX Handler sets to a valid buffer that it has created.

(IN/OUT) replyDataLen

On input, this is 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 the NCPX Handler stored in the reply buffer.

You might want to have an NCPX Handler return other status information (such as failure reasons) to the client. If you do this, do not use any return values that have been defined for this call. The risk in returning values other than SUCCESSFUL is that future versions of NetWare Services might return values that you have defined, leaving you unsure of the return value's meanings.

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

The ConnectionEventHandler callback parameter 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 ConnectionEventHandler when you register the NCP extension.

The routine pointed to by ConnectionEventHandler has the following parameters:

(IN) connection

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 NCPX client.)

(IN) eventType

This names the type of event that is being reported. This parameter returns the following values:

CONNECTION_BEING_FREED
Either the client has made a call to return its connection, or the server has cleared the connection (watchdog).
CONNECTION_BEING_LOGGED_OUT
The client has made a call to log out.

The routine pointed to by ConnectionEventHandler does not return a value.

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

(IN) client

A pointer to an NCPExtensionClient structure, containing the connection and task of the calling client.

typedef struct { 
    LONG connection; 
    LONG task; 
} NCPExtensionClient;

(IN) replyBuffer

A pointer to a buffer whose information has been returned to the client.

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(3xti_ncp).

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) NCPExtensionName: Specifies the name of the NCP extension.
(IN) NCPExtensionHandler: Specifies the function that is to be executed when the NCP extension is called with NWSendNCPExtensionRequest. (See ``Description'' for the use of NULL in this field.)
(IN) ConnectionEventHandler: Specifies the function that to be called when a connection is logged out or terminated on the server. (See ``Description'' for the use of NULL in this field.)
(IN) ReplyBufferManager: Specifies a reply buffer manager that can be used to manage buffers used to reply to NCP extension requests. (See ``Description'' for the use of NULL in this field.)
(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
255 (0xFF): ERR_BAD_PARAMETER: the NCPExtensionName parameter was longer than the 32-byte limit

Examples

   int 
   HandlerMain(int argc, char argv[]) 
   { 
       int ccode; 
       void queryData; 
    
       NCPX_EventLoopState el_state; 
   
 
       /*********************************************/ 
       /* Register the extension. */ 
   
 
       ccode = NWRegisterNCPExtension("TEST EXTENSION", 
           NCP_callback, 
           ConnectionEvent_callback, 
           NULL,    /* No reply-buffer-manager callback. */ 
           1,       /* major version */ 
           2,       /* minor version */ 
           3,       /* revision */ 
           &queryData); 
       if ( ccode != 0) { 
           printf("%s had failure (ccode %d) registering NCP Extension.\n", 
                  ExecName, ccode); 
           exit(1); 
       }

References

NWDeRegisterNCPExtension(3xti_ncp), NWRegisterNCPExtensionByID(3xti_ncp)