Carbon


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
);
Parameter descriptions
notifier

On input, a value of type NSLClientNotifyUPP that points to your application’s notification routine. Your notification routine will be called when data is available, when the lookup is complete, or when an error occurs.

contextPtr

On input, an untyped pointer to arbitratry data that the NSL Manager will pass to your application’s 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.

theClient

On input, an NSLClientRef obtained by previously calling NSLOpenNavigationAPI that identifies the NSL Manager session.

ref

On output, a pointer to the resulting lookup request.

bufPtr

On input, a pointer to the buffer in which lookup results are to be placed.

bufLen

On input, the length of the buffer pointed to by bufPtr.

infoPtr

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.

function result

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).

DISCUSSION

The NSLPrepareRequest function creates a lookup request, which your application later uses as a parameter when it calls NSLStartNeighborhoodLookup or NSLStartServicesLookup.

Your application’s 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 application’s 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 application’s 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)