NWSendNCPExtensionFraggedRequest(3nw)


NWSendNCPExtensionFraggedRequest -- sends request to NCP Extension

Synopsis

   #include <ncpext.h> 
   

int NWSendNCPExtensionFraggedRequest (LONG NCPExtensionID, const struct NCPExtensionMessageFrag *requestFrag, struct NCPExtensionMessageFrag *replyFrag);

Description

The parameters are as follows:

NCPExtensionID
(IN) Specifies the ID of the NCP Extension to process the request.

requestFrag
(IN) Points to information about the lengths and locations of the fragmented data for the NCP Extension handler to process.

replyFrag
(IN/OUT) Point to a NCPExtensionMessageFrag structure. On input, specifies the maximum length of the data to return and where to place on the data. On output, is set to specify the length of all the data that was returned and the locations where the data was placed.

Return values

0 (0x00) SUCCESSFUL
1-16 - A communications error has occurred. (See niterror.h.)
126 (0x7E) ERR_NCPEXT_TRANSPORT_PROTOCOL_VIOLATION
The message transport mechanism entered a bad state in the protocol.
150 (0x96) ERR_NO_ALLOC_SPACE
There was not enough memory available on the server to allocate space for the message.
252 (0xFC) ERR_NCPEXT_SERVICE_PROTOCOL_VIOLATION
The service provider tried to return more data than the reply buffer could hold.
254 (0xFE) ERR_NCPEXT_NO_HANDLER
The NCP exception handler could not be found.

 
 --------------------------------------------------------- 
| 0   |  (0x00)|  SUCCESSFUL                             | 
|-----|--------|-----------------------------------------| 
| 1-16|  -     |  A communications                       | 
|     |        |  error has occurred.                    | 
|     |        |  (See niterror.h.)                      | 
|-----|--------|-----------------------------------------| 
| 126 |  (0x7E)|  ERR_NCPEXT_TRANSPORT_PROTOCOL_VIOLATION| 
|     |        |  The message                            | 
|     |        |  transport mechanism                    | 
|     |        |  entered a bad state                    | 
|     |        |  in the protocol.                       | 
|-----|--------|-----------------------------------------| 
| 150 |  (0x96)|  ERR_NO_ALLOC_SPACE                     | 
|     |        |  There was not                          | 
|     |        |  enough memory                          | 
|     |        |  available on the                       | 
|     |        |  server to allocate                     | 
|     |        |  space for the                          | 
|     |        |  message.                               | 
|-----|--------|-----------------------------------------| 
| 252 |  (0xFC)|  ERR_NCPEXT_SERVICE_PROTOCOL_VIOLATION  | 
|     |        |  The service                            | 
|     |        |  provider tried to                      | 
|     |        |  return more data                       | 
|     |        |  than the reply                         | 
|     |        |  buffer could hold.                     | 
|-----|--------|-----------------------------------------| 
| 254 |  (0xFE)|  ERR_NCPEXT_NO_HANDLER                  | 
|     |        |  The NCP exception                      | 
|     |        |  handler could not                      | 
|     |        |  be found.                              | 
|-----|--------|-----------------------------------------| 

Other return values generated by the NCP Extension handler can be returned here.

Notices

You call NWSendNCPExtensionFraggedRequest when you want send your NCP Extension handler information located at various locations in the client's memory. This avoids copying the information into a single buffer before sending it to your NCP Extension.

You can also call NWSendNCPExtensionFraggedRequest to have the reply data placed into up to four specific locations, eliminating the need for you to copy the data from a reply buffer.

If your NCP Extension uses a single input buffer and/or a single output buffer, you can use NWSendNCPExtensionRequest instead of this function.

NCPExtensionID is the ID of the NCP Extension. If your NLM registers its NCP Extension by a specific ID, you use that ID when calling this function. If your NLM registers its NCP Extension by name, you must call NWGetNCPExtensionInfo or NWScanNCPExtensions to obtain the ID before you call this function.

The requestFrag parameter is a pointer to a structure of type NCPExtensionMessageFrag, which is defined as follows:

   struct NCPExtensionMessageFrag { 
      LONG totalMessageSize; 
      LONG fragCount; 
      struct FragElement fragList[4]; 
   } 
The totalMessageSize field is the length of all of the fragments in bytes.

The fragCount field is the number of FragElements stored in the fragList.

The fragList field is an array of up to four structures of type FragElement. The FragElement structure is defined as follows:

   struct FragElement{ 
      void *ptr; 
      LONG size; 
   } 
The ptr field is a pointer to the data.

The size field is the length of the message in bytes.

If requestFrag parameter is NULL, no request data is sent to the server.

Like requestFrag, the replyFrag parameter is also a pointer to a structure of type NCPExtensionMessageFrag, except this structure is used to tell NWSendNCPExtensionFraggedRequest where to place the reply data when it is returned by the NCP Extension.

On input, the replyFrag.totalMessageSize field should be set to the limit (in bytes) for all of the data that is returned. Each of the size fields in the FragElement structures should be set to the limit of bytes that this function can place in the memory pointed to by the structure's associated ptr field.

Before returning, NWSendNCPExtensionFraggedRequest copies up to replyFrag.totalMessageSize bytes from the server and place them into the locations specified in the fragList array of the replyFrag buffer. It then sets replyFrag.totalMessageSize to reflect the actual number of bytes transferred.

If replyFrag is NULL, no data is copied from the server.


NOTE: The information in the replyFrag buffer is valid only if NWSendNCPExtensionFraggedRequest returns SUCCESSFUL.

The request and reply buffers of the client must be reproduced on the server, so the maximum size of the buffers you can use depends upon the memory available on the server that registers the NCP Extension. When NWSendNCPExtensionFraggedRequest is called, it attempts to allocate server memory for two message buffers of size (in bytes) requestFrag.totalMessageSize and replyFrag.totalMessageSize. If it cannot allocate the space, it returns ERR_NO_ALLOC_SPACE. If it returns ERR_NO_ALLOC_SPACE, you might retry several times, since server memory use is dynamic.

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

Services

NCP Extension

References

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