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.
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
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 EchoServerConnEventHandler(LONG connection, LONG eventType)
{
ConsolePrintf("\nECHO SERVER notified of connection %d logged out or returned\n",
connection);
}