NWGetNCPExtensionInfoByID(3nw)


NWGetNCPExtensionInfoByID -- query for NCP Extension by ID

Synopsis

   #include <ncpext.h> 
   

int NWGetNCPExtensionInfoByID ( LONG *NCPExtensionID, char *NCPExtensionName, BYTE *majorVersion, BYTE *minorVersion, BYTE *revision, void *queryData);

Description

The parameters are as follows:

NCPExtensionID
(IN) Points to the ID of the desired NCP Extension.

NCPExtensionName
(OUT) Points to the name of NCP Extension that is associated with the ID passed in with NCPExtensionID. (Can be set to NULL if this information is not needed.)

majorVersion
(OUT) Points to the major version number of the NCP Extension provider. (Can be set to NULL if this information is not needed.)

minorVersion
(OUT) Points to the minor version number of the NCP Extension provider. (Can be set to NULL if this information is not needed.)

revision
(OUT) Points to the revision number of the NCP Extension provider. (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. (See <niterror.h>.)

 
 ----------------------------------------------------------- 
| 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. (See| 
|     |        |                    |  <niterror.h>.)      | 
|-----|--------|--------------------|----------------------| 

Notices

NWGetNCPExtensionInfo, NWGetNCPExtensionInfoByID, NWScanNCPExtensions, NWSendNCPExtensionFraggedRequest and NWSendNCPExtensionRequest are the client (NLM and workstation) functions for accessing NCP Extensions. If you know the ID of the NCP Extension, you can call NWGetNCPExtensionInfoByID for the following purposes: Before a client can access an NCP Extension, it must first call NWGetNCPExtensionInfo (NLM), NWGetNCPExtensionInfoByID, or NWScanNCPExtensions to see if the extension has been registered. If the NCP Extension has been registered, NWGetNCPExtensionInfoByID returns SUCCESSFUL; otherwise, it returns ERR_NO_ITEMS_FOUND. (NWGetNCPExtensionInfo and NWScanNCPExtensions return the same information but they use the name of the NCP Extension, rather than the ID.)

NCPExtensionID points to the ID of the NCP Extension. This can be a dynamic ID returned from NWGetNCPExtensionInfo or NWScanNCPExtensions, or it can be a static ID assigned by Developer Support.

The NCPExtensionName points to the name of the NCP Extension that is associated with the ID pointed to by NCPExtensionID. If you are using a static ID, you might want to check this name (on the first call) to verify that the name returned is the same as your NCP Extension's name.

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

There are some cases where NWGetNCPExtensionInfoByID 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 NWGetNCPExtensionInfoByID.

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 or NWRegisterNCPExtensionByID. If the information you want is in the NLM's queryData buffer, you can use NWGetNCPExtensionInfoByID 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 not 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, and it registers its NCP Extensions with NWRegisterNCPExtensionByID, the IDs for the extensions are the same.

If the NLM is reloaded, and it registers its NCP Extensions by name with NWRegisterNCPExtension, the NCP Extensions do not have the same NCP Extension IDs, even though they have the same names. If you register your NCP Extensions by name and any of the client (NLM or workstation) NCP Extension calls return ERR_NO_ITEMS_FOUND (or ERR_NCPEXT_NO_HANDLER after previously working properly), the client should call NWGetNCPExtensionInfo (NLM). This returns the new NCPExtensionID if the NCP Extension has been deregistered and then reregistered.


For a description of NCP Extensions, see ``NCP extensions''.

Services

NCP Extension

References

NWDeRegisterNCPExtension(3nw), NWGetNCPExtensionInfo(3nw), NWRegisterNCPExtension(3nw), NWScanNCPExtensions(3nw), NWSendNCPExtensionRequest(3nw)
30 January 1998
© 1998 The Santa Cruz Operation, Inc. All rights reserved.