![]() |
NSLStartServicesLookup |
||||
Header: | NSL.h | Carbon status: | Supported | |
Looks for services.
NSLError NSLStartServicesLookup ( NSLRequestRef ref, NSLNeighborhood neighborhood, NSLTypedDataPtr requestData, NSLClientAsyncInfo *asyncInfo );
On input, an NSLRequestRef created by previously calling NSLPrepareRequest.
On input, an NSLNeighborhood value created by previously calling NSLMakeNewNeighborhood.
On input, a parameter block that describes the search parameters. To format requestData properly, call NSLMakeServicesRequestPB.
On input, a pointer to a NSLClientAsyncInfo structure obtained by calling NSLPrepareRequest.
If the value of NSLError.theErr is noErr, NSLStartServicesLookup returned successfully. Other possible values are kNSLNotInitialized, kNSLSearchAlreadyInProgress, kNSLNoPluginsForSearch, kNSLNullNeighborhoodPtr, and kNSLBufferTooSmallForData.
The NSLStartServicesLookup function starts a service lookup.
For any NSLRequestRef, only one neighborhood or service lookup can be ongoing at any one time.
When the NSL Manager calls your applications notification routine, it should check the value of asyncInfo.searchState, which contains one of the following values:
kNSLSearchStateBufferFull = 1,
kNSLSearchStateOnGoing = 2,
kNSLSearchStateComplete = 3,
kNSLSearchStateStalled = 4
If the value of asyncInfo.searchState is kNSLSearchStatusBufferFull, your application should process the data returned in asyncInfo.resultBuffer and return, thereby continuing the lookup.
If the value of asyncInfo.searchState is kNSLSearchStateOnGoing, the value of asyncInfo.alertInterval or asyncInfo.alertThreshold has been reached. Your application should process the data returned in asyncInfo.resultBuffer and return, thereby continuing the lookup.
If the value of asyncInfo.searchState is kNSLSearchStateComplete, the lookup is complete. Your application should process the data returned in asyncInfo.resultBuffer.
If the value of asyncInfo.searchState is kNSLSearchStateStalled, the value of asyncInfo.alertInterval or asyncInfo.maxSearchTime has been reached, but there is no data in the result buffer. One or more plug-ins for this lookup is waiting to receive data from a server but has not yet timed out. If the value of asyncInfo.searchState is noErr, your applications notification routine should ignore the notification and return immediately, thereby resuming the lookup.
If NSLStartServicesLookup returns kNSLBufferTooSmallForData, the value of asyncInfo.maxBuffserSize is too small to hold an item that would otherwise have been returned. Your notification routine can cancel and restart the lookup, or it can ignore the error and return, thereby resuming the lookup even though some data will be lost.
If more than one plug-in participates in a lookup, the result buffer may contain valid data even though NSLStartServicesLookup returns an error code from one of the plug-ins. If the value of asyncInfo.searchState is kNSLSearchStateBufferFull, your application should process the data in the result buffer.
To cancel an ongoing lookup, call NSLCancelRequest.
NSLGetNextUrl for information about processing the data in the result buffer. NSLDeleteRequest for information about deleting a lookup request that is no longer needed.
© 2000 Apple Computer, Inc. (Last Updated 7/13/2000)