![]() |
NSLPrepareRequest |
||||
Header: | NSL.h | Carbon status: | Supported | |
Creates a lookup request.
NSLError NSLPrepareRequest ( NSLClientNotifyUPP notifier, void *contextPtr, NSLClientRef theClient, NSLRequestRef *ref, char *bufPtr, UInt32 bufLen, NSLClientAsyncInfoPtr *infoPtr );
On input, a value of type NSLClientNotifyUPP that points to your applications notification routine. Your notification routine will be called when data is available, when the lookup is complete, or when an error occurs.
On input, an untyped pointer to arbitratry data that the NSL Manager will pass to your applications notification routine when that routine is called. Your application can use contextPtr to associate any particular execution of your notification routine with any particular lookup request.
On input, an NSLClientRef obtained by previously calling NSLOpenNavigationAPI that identifies the NSL Manager session.
On output, a pointer to the resulting lookup request.
On input, a pointer to the buffer in which lookup results are to be placed.
On input, the length of the buffer pointed to by bufPtr.
On output, infoPtr contains default information about how the search is to be conducted. Your application can change the defaults before it starts the lookup.
If the value of NSLError.theErr is noErr, the request was created. Other possible values include kNSLNotInitialized, kNSLDuplicateSearchInProgress, kNSLBadClientInfoPtr, and kNSLErrNullPtrError (if the value of infoPtr is NULL).
The NSLPrepareRequest function creates a lookup request, which your application later uses as a parameter when it calls NSLStartNeighborhoodLookup or NSLStartServicesLookup.
Your applications notification routine will be called when the result buffer contains data, the result buffer is full, when the lookup is complete, or when an error occurs. Your application can cause your applications notification routine to be called at a specified interval, when a specified number of items is in the result buffer, or when a specified amount of time has elapsed by modifying the value of the alertInterval, alertThreshold, and maxSearchTime fields, respectively, of the NSLClientAsyncInfo structure pointed to by infoPtr.
The NSL Manager does not call your applications notification routine at interrupt time, so your notification routine can allocate memory.
When your application no longer needs the lookup request, it should call NSLDeleteRequest to reclaim memory associated with the request.
If NSLPrepareRequest returns kDuplicateSearchInProgress, there is an ongoing lookup that is using an identical NSLRequestRef. Your application can ignore this warning, delete the newly created NSLRequestRef, or cancel the lookup that is using the identical NSLRequestRef.
© 2000 Apple Computer, Inc. (Last Updated 7/13/2000)