Edit

Searching a Distributed Routing Table

  • Article

Before an application can search the Distributed Routing Table (DRT), a search query must be created. The desired key value is specified by the application when the DrtStartSearch function is called. The behavior of the search is determined by information specified by the application in the DRT_SEARCH_INFO structure.

Typically, an application event is signaled when the search discovers results and another at the conclusion of the search. However, if fIterative is set in DRT_SEARCH_INFO, an application event can be signaled when contact is made with each node along the way.

After an event is signaled, the application then calls the DrtGetSearchResult function for the results. If the returned code is S_OK, the results are pointed to in the DRT_SEARCH_RESULT structure returned by the API. The returned results fall into the range of values specified in DRT_SEARCH_INFO. In the event that the search finds no matches, only the DRT_E_NO_MORE value will be returned at the conclusion of result returns.

The following information details how the members contained in DRT_SEARCH_INFO allow an application to specifically dictate the search behavior of the DRT infrastructure:

fAllowCurrentInstanceMatch

By default, DRT search results include only matches found outside of the local node. Setting fAllowCurrentInstanceMatch specifies that the search results also include matches found in the local DRT instance.

cMaxEndpoints

The quantity and range of the results returned by the search are specified by the application with the cMaxEndpoints (quantity) and the pMinimumKey and pMaximumKey (range) values, and referenced by DRT_SEARCH_INFO.

When cMaxEndpoints = 1, the DRT infrastructure searches for a key, returning one match within the range specified by the pMinimumKey and pMaximumKey values in DRT_SEARCH_INFO. This match can be either an exact match or the nearest match within range. If a match is not found, DRT_E_NO_MORE is returned.

If cMaxEndpoints > 1, the DRT infrastructure will return matches within the range up to the value of cMaxEndpoints. The returned matches can contain an exact match or the nearest match results within range. Additionally, if pMinimumKey and pMaximumKey are set to the same value, a search is carried out only for that value, returning DRT_E_NO_MORE if it is not found.

fAnyMatchInRange

The fAnyMatchInRange member indicates whether the search will stop after the first match is located within the specified range, or if the search will continue for the closest match to the key specified in the DrtStartSearch API. When fAnyMatchInRange is set, the search is carried out with cMaxEndpoints = 1 regardless of the specified value of cMaxEndpoints in DRT_SEARCH_INFO.

fIterative

The fIterative member specifies if each node contacted by the DRT infrastructure during the search will have the key/endpoint data associated with it made available to the application via DRT_SEARCH_RESULT. By setting fIterative to TRUE, the value of cMaxEndpoints = 1 will be forced. When fIterative is set to TRUE within a search query for the DRT, the application is called back after contact with each node or "hop." Each hop result contains a key indicating which node the DRT will search next. A hop result is returned via DrtGetSearchResult as a DRT_MATCH_INTERMEDIATE result.

pMinimumKey and pMaximumKey

The pMinimumKey and pMaximumKey members can be used to search for keys falling within a range. If the fAnyMatchInRange member is set to FALSE, the DRT will return the closest key(s) to the search target (specified using the pKey argument passed in the DrtStartSearch function) falling within the range. Note that the pKey argument passed to DrtStartSearch must fall within the range defined by pMinimumKey and pMaximumKey. To search for a precise key, set pMinimumKey, pMaximumKey and pKey to the same value.

Registering and Deregistering Keys

About Distributed Routing Tables

Distributed Routing Table API Reference