|
WSALookupServiceBegin
The Windows Sockets WSALookupServiceBegin function initiates a client query that is constrained by the information
contained within a WSAQUERYSET structure. WSALookupServiceBegin only returns a handle, which should be used by subsequent calls to WSALookupServiceNext to get the actual results.
INT WSALookupServiceBegin (
LPWSAQUERYSET lpqsRestrictions,
|
| DWORD dwControlFlags,
|
| LPHANDLE lphLookup
|
| );
|
|
Parameters
lpqsRestrictions
[in] Contains the search criteria. See below for details.
dwControlFlags
[in] Controls the depth of the search.
LUP_DEEP
| Query deep as opposed to just the first level.
| LUP_CONTAINERS
| Return containers only
| LUP_NOCONTAINERS
| Do not return any containers
| LUP_FLUSHCACHE
| If the provider has been caching information, ignore the cache and go query
the name space itself.
| LUP_NEAREST
| If possible, return results in the order of distance. The measure of distance
is provider specific.
| LUP_RES_SERVICE
| This indicates whether prime response is in the remote or local part of
CSADDR_INFO structure. The other part needs to be "usable" in either case.
| LUP_RETURN_ALIAS
| Any available alias information is to be returned in successive calls to WSALookupServiceNext, and each alias returned will have the RESULT_IS_ALIAS flag set.
| LUP_RETURN_NAME
| Retrieve the name
| LUP_RETURN_TYPE
| Retrieve the type
| LUP_RETURN_VERSION
| Retrieve the version
| LUP_RETURN_COMMENT
| Retrieve the comment
| LUP_RETURN_ADDR
| Retrieve the addresses
| LUP_RETURN_BLOB
| Retrieve the private data
| LUP_RETURN_ALL
| Retrieve all of the information
|
lphLookup
[out] Handle to be used when calling WSALookupServiceNext in order to start retrieving the results set.
Remarks
If LUP_CONTAINERS is specified in a call, all other restriction values should
be avoided. If any are supplied, it is up to the name service provider to
decide if it can support this restriction over the containers. If it cannot, it
should return an error.
Some name service providers may have other means of finding containers. For
example, containers might all be of some well-known type, or of a set of
well-known types, and therefore a query restriction may be created for finding them. No
matter what other means the name service provider has for locating containers,
LUP_CONTAINERS and LUP_NOCONTAINERS take precedence. Hence, if a query
restriction is given that includes containers, specifying LUP_NOCONTAINERS will
prevent the container items from being returned. Similarly, no matter the query
restriction, if LUP_CONTAINERS is given, only containers should be returned. If a
name space does not support containers, and LUP_CONTAINERS is specified, it
should simply return WSANO_DATA.
The preferred method of obtaining the containers within another container, is
the call:
dwStatus = WSALookupServiceBegin(
lpqsRestrictions,
LUP_CONTAINERS,
lphLookup);
followed by the requisite number of WSALookupServiceNext calls. This will return all containers contained immediately within the
starting context; that is, it is not a deep query. With this, one can map the
address space structure by walking the hierarchy, perhaps enumerating the content of
selected containers. Subsequent uses of WSALookupServiceBegin use the containers returned from a previous call.
Forming Queries
As mentioned above, a WSAQUERYSET structure is used as an input parameter to WSALookupBegin in order to qualify the query. The following table indicates how the
WSAQUERYSET is used to construct a query. When a field is marked as (Optional) a NULL pointer may be supplied, indicating that the field will not be used as
a search criteria. See section Query-Related Data Structures for additional information.
WSAQUERYSET Field Name
| Query Interpretation
| dwSize
| Must be set to sizeof(WSAQUERYSET). This is a versioning mechanism.
| dwOutputflags
| Ignored for queries.
| lpszServiceInstanceName
| (Optional) Referenced string contains service name. The semantics for wildcarding within
the string are not defined, but may be supported by certain name space
providers.
| lpServiceClassId
| (Required) The GUID corresponding to the service class.
| lpVersion
| (Optional) References desired version number and provides version comparison semantics
(that is, version must match exactly, or version must be not less than the value
supplied).
| lpszComment
| Ignored for queries.
| dwNameSpace1
| Identifier of a single name space in which to constrain the search, or NS_ALL
to include all name spaces.
| lpNSProviderId
| (Optional) References the GUID of a specific name space provider, and limits the query to
this provider only.
| lpszContext
| (Optional) Specifies the starting point of the query in a hierarchical name space.
| dwNumberOfProtocols
| Size of the protocol constraint array, may be zero.
| lpafpProtocols
| (Optional) References an array of AFPROTOCOLS structure. Only services that utilize these
protocols will be returned.
| lpszQueryString
| (Optional) Some namespaces (such as whois++) support enriched SQL like queries which are
contained in a simple text string. This parameter is used to specify that
string.
| dwNumberOfCsAddrs
| Ignored for queries.
| lpcsaBuffer
| Ignored for queries.
| lpBlob
| (Optional) This is a pointer to a provider-specific entity.
|
- See the Important note below
|
|
Important In most instances, applications interested in only a particular transport
protocol should constrain their query by address family and protocol rather than
by name space. This would allow an application that needs to locate a TCP/IP
service, for example, to have its query processed by all available name spaces
such as the local hosts file, DNS, and NIS.
Return Values
The return value is zero if the operation was successful. Otherwise, the value
SOCKET_ERROR is returned, and a specific error number may be retrieved by
calling WSAGetLastError.
Error Codes
WSANO_DATA
| The name was found in the database but no data matching the given restrictions
was located.
| WSANOTINITIALIZED
| The Windows Sockets 2 DLL has not been initialized. The application must first
call WSAStartup before calling any Windows Sockets functions.
| WSASERVICE_NOT_FOUND
| No such service is known. The service cannot be found in the specified name
space.
|
See Also
WSALookupServiceEnd and WSALookupServiceNext
| Last news from Greatis Software |
 |
|
Nostalgia .Net |
|
.Net is powerful, but not all-powerful, so sometimes we need to use Win32 API for our .Net applications. It's simple enough with Platform Invoke if you have Win32 skill, but we do not always have time to dig the ancient documentation, declare the special types that are compatible with Win32, find the values of the Win32's constants and so on. Nostalgia .Net offers several simple-to-use classes, and components that will allow you to forget about the headache of Win32 and just use the power of Win32 in your application the same way as you use the native. Net classes. More » |
| Recommended software for developers |
 |
|
Ultimate Pack |
|
Component pack for Delphi and C++ Builder that contains runtime form designer, runtime object inspector, print suite and much more for the very special price. More » |
 |
|
Form Designer .Net |
|
Unique runtime form design solution that allows to edit any form in .Net WinForms application at runtime with full source codes for only 300 euro! More » |
 |
|
Print Suite .Net |
|
Print Suite .Net is a set of components for easy printing texts, images and grids from your WinForms applications. Full C# source codes are available More » |
 |
|
Gradient Controls .Net |
|
Gradient Controls .Net offers controls with gradient background feature. Labels, panels and so on... Full C# source codes are available More » |
 |
|
Greatis iGrid |
|
iGrid plots drawing grid right over your desktop, so you can use it everywhere, with any drawing application without any special plugins for different graphic editors. More » |
All the contacts and projectsDmitry Vasiliev (just.dmitry)
Related LinksSoftware for Visual Studio .NET developers
Software for Delphi and C++ Builder developers
Software for Visual Basic 6 developers
Delphi Tips&Tricks
MegaDetailed.NET More Online Helps Win32 Programmer's Reference
Win32 Multimedia Programmer's Reference
OLE Programmer's Reference
Microsoft Windows Pen API Programmer's Reference
Microsoft Windows Sockets 2 Reference
Microsoft Windows Telephony API (TAPI) Programmer's Reference
Unix Manual Pages
|
