NWGetNCPExtensionInfo(3nw)

NWGetNCPExtensionInfo -- queries NCP Extension

Synopsis

   #include <ncpext.h> 
    
   int NWGetNCPExtensionInfo ( 
      const char  NCPExtensionName, 
      LONG        NCPExtensionID, 
      BYTE        majorVersion, 
      BYTE        minorVersion, 
      BYTE        revision, 
      void        queryData); 
    
   #include <nwncpext.h> 
   or 
   #include <nwcalls.h> 
   
 
   NWCCODE N_API NWGetNCPExtensionInfo( 
      NWCONN_HANDLE   conn, 
      nuint32         NCPExtensionID, 
      pnstr8          NCPExtensionName, 
      pnuint8         majorVersion, 
      pnuint8         minorVersion, 
      pnuint8         revision, 
      pnuint8         queryData);

Description

Note that two versions of this function exist, depending on the header file used.

The parameters are as follows:

conn: <nwncpext.h> or <nwcalls.h> version only: (IN) Indicates the NetWare server connection handle.
NCPExtensionName: (IN) Points to the name of the desired NCP Extension.
NCPExtensionID: (OUT) Points to the ID of the desired NCP Extension.
majorVersion: (OUT) Points to the major version number of the NCP Extension provider. (Optional: can be set to NULL if this information is not needed.)
minorVersion: (OUT) Points to the minor version number of the NCP Extension provider. (Optional: can be set to NULL if this information is not needed.)
revision: (OUT) Points to the revision number of the NCP Extension provider. (Optional: can be set to NULL if this information is not needed.)
queryData: (OUT) Points to 32 bytes of information from the NCP Extension.

Return values

0 (0x00) SUCCESSFUL The extension was found, and the non-null output parameters were filled.

255 (0xFF) ERR_NO_ITEMS_FOUND The extension name was not found.

1-16 - - A communications error occurred.

 
 0      (0x00)   SUCCESSFUL           The extension 
                                      was found, and 
                                      the non-null 
                                      output 
                                      parameters were 
                                      filled. 
 255    (0xFF)   ERR_NO_ITEMS_FOUND   The extension 
                                      name was not 
                                      found. 
 1-16   -        -                    A 
                                      communications 
                                      error occurred.

Notices

NWGetNCPExtensionInfo (NLM), NWScanNCPExtensions, and NWSendNCPExtensionRequest are the client (NLM and workstation) functions for accessing NCP Extensions. If you know the name of the NCP Extension you want to access, such as ``ECHO SERVER,'' you can call NWGetNCPExtensionInfo (NLM) for the following purposes:

To see if the NCP Extension is registered.
To check the version of the NCP Extension.
To get the NCP Extension ID number for use when calling NWSendNCPExtensionRequest.
To receive 32 bytes of information from the NCP Extension without calling NWSendNCPExtensionRequest.

Before a client can access an NCP Extension, it must first call NWGetNCPExtensionInfo (NLM) or NWScanNCPExtensions to see if the Extension has been registered and to receive the Extension ID needed to call the NCP Extension. If the NCP Extension has been registered, NWGetNCPExtensionInfo (NLM) returns SUCCESSFUL; otherwise, it returns ERR_NO_ITEMS_FOUND. NWScanNCPExtensions returns the same information, but it must be called iteratively until the NCP Extension name is found.)

The NCPExtensionName can be any character string, up to 32 bytes plus a NULL terminator. The NCP Extension names are case sensitive and must be unique for each NCP Extension. One suggestion is to name the NCP Extension the same as your NLM. To avoid naming conflicts, you should clear your NCP Extension's name through Developer Support.

You provide the fields majorVersion, minorVersion, and revision when you call NWRegisterNCPExtension. If you are going to have different versions or revisions of the NCP Extension, the client can use these fields to verify that the extension is the correct version. If you do not want to use this information, pass NULL as the parameters.

The server side and the client side of NCP Extensions should be implemented as matched sets, meaning the client side knows what the server side is expecting and what it can return. The client side also needs to know the name of the NCP Extension.

There are some cases where NWGetNCPExtensionInfo (NLM) can return all of the information your client needs, eliminating the need to call NWSendNCPExtensionRequest or to have an NCP Extension handler. This information is placed in the client's queryData buffer, whose address is passed as a parameter to NWGetNCPExtensionInfo.

This technique can be used if the service-providing NLM is periodically updating its queryData buffer (with 32 bytes or less of information) whose address was returned to the NLM when it called NWRegisterNCPExtension. If the information you want is in the NLM's queryData buffer, you can use NWGetNCPExtensionInfo to copy the contents of the service-providing NLM's queryData buffer into your client's queryData buffer. This method is useful only if a one-way server-to-client message is sufficient.

If you are using the queryData buffer, pass NULL for the queryData parameter.

NOTE: If an NLM is unloaded, all NCP Extensions associated with it are deregistered. If the NLM is reloaded, its NCP Extensions do not have the same NCP Extension IDs, even though they have the same names. If any of the client (NLM or workstation) NCP Extension functions return ERR_NO_ITEMS_FOUND (or ERR_NCPEXT_NO_HANDLER after previously working properly), the client should call NCPGetExtensionInfo again. This returns the new NCPExtensionID if the NCP Extension has been deregistered and then reregistered.

Services

NCP Extension

NCP calls

0x2222 23 17 Get File Server Information

0x2222 36 00 Scan NCP Extensions

0x2222 36 02 Scan Loaded Extensions By Name

0x2222 36 05 Get NCP Extension Info

 
 0x2222   23   17   Get File Server Information 
 0x2222   36   00   Scan NCP Extensions 
 0x2222   36   02   Scan Loaded Extensions By Name 
 0x2222   36   05   Get NCP Extension Info

References

NWDeRegisterNCPExtension(3nw), NWGetNCPExtensionInfoByID(3nw), NWRegisterNCPExtension(3nw), NWScanNCPExtensions(3nw), NWSendNCPExtensionRequest(3nw)

0	(0x00)	SUCCESSFUL	The extension was found, and the non-null output parameters were filled.
255	(0xFF)	ERR_NO_ITEMS_FOUND	The extension name was not found.
1-16	-	-	A communications error occurred.

0x2222	23	17	Get File Server Information
0x2222	36	00	Scan NCP Extensions
0x2222	36	02	Scan Loaded Extensions By Name
0x2222	36	05	Get NCP Extension Info