SetService
Important The SetService
function is obsolete. For the convenience of Windows Sockets 1.1 developers,
the reference material is below.
In Windows
Sockets 2, this functionality is realized with the functions detailed in Protocol-Independent
Name Resolution.
The SetService
function registers or deregisters a network service within
one or more
name spaces. The function can also add or remove a network service type within
one or more name spaces.
INT SetService(
|
DWORD dwNameSpace, |
// specifies name
space(s) to operate within |
|
DWORD dwOperation, |
// specifies
operation to perform |
|
DWORD dwFlags, |
// set of bit flags
that modify function operation |
|
LPSERVICE_INFO lpServiceInfo, |
// points to
structure containing service information |
|
LPSERVICE_ASYNC_INFO lpServiceAsyncInfo, |
// reserved for
future use, must be NULL |
|
LPDWORD lpdwStatusFlags |
// points to set of
status bit flags |
|
); |
|
Parameters
dwNameSpace
Specifies the
name space, or a set of default name spaces, within which the function will
operate.
Use one of
the following constants to specify a name space:
|
Value |
Name
Space |
|
NS_DEFAULT |
A set of
default name spaces. The function queries each name space within this set.
The set of default name spaces typically includes all the name spaces
installed on the system. System administrators, however, can exclude
particular name spaces from the set. NS_DEFAULT is the value that most
applications should use for dwNameSpace. |
|
NS_DNS |
The Domain
Name System used in the Internet to resolve the name of the host. |
|
NS_NDS |
The NetWare
4 provider. |
|
NS_NETBT |
The NetBIOS
over TCP/IP layer. All Windows NT and Windows 95 systems register their
computer names with NetBIOS. This name space is used to convert a computer
name to an IP address that uses this registration. |
|
NS_SAP |
The NetWare
Service Advertising Protocol. This can access the Netware bindery, if
appropriate. NS_SAP is a dynamic name space that enables the registration of
services. |
|
NS_TCPIP_HOSTS |
Lookup
value in the <systemroot>\system32\drivers\etc\posts file. |
|
NS_TCPIP_LOCAL |
Local
TCP/IP name resolution mechanisms, including comparisons against the local
host name and lookup value in the cache of host to IP address mappings. |
dwOperation
Specifies the
operation that the function will perform. Use one of the following values to
specify an operation:
|
Value |
Meaning |
|
SERVICE_REGISTER |
Register
the network service with the name space. This operation may be used with the
SERVICE_FLAG_DEFER and SERVICE_FLAG_HARD bit flags. |
|
SERVICE_DEREGISTER |
Deregister
the network service from the name space. This operation can be used with the
SERVICE_FLAG_DEFER and SERVICE_FLAG_HARD bit flags. |
|
SERVICE_FLUSH |
Perform any
operation that was called with the SERVICE_FLAG_DEFER bit flag set to
one. |
|
SERVICE_ADD_TYPE |
Add a
service type to the name space. For this
operation, use the ServiceSpecificInfo member of the SERVICE_INFO structure pointed to by lpServiceInfo
to pass a SERVICE_TYPE_INFO_ABS structure. You must also set the ServiceType
member of the SERVICE_INFO structure. Other SERVICE_INFO members
are ignored. |
|
SERVICE_DELETE_TYPE |
Remove a
service type, added by a previous call specifying the SERVICE_ADD_TYPE
operation, from the name space. |
dwFlags
A set of bit
flags that modify the function s operation.
You can set one or more of the following bit flags:
|
Value |
Name
Space |
|
SERVICE_FLAG_DEFER |
This bit
flag is valid only if the operation is SERVICE_REGISTER or SERVICE_DEREGISTER. If this bit
flag is one, and it is valid, the name-space provider should defer the
registration or deregistration operation until a SERVICE_FLUSH operation is
requested. |
|
SERVICE_FLAG_HARD |
This bit
flag is valid only if the operation is SERVICE_REGISTER or
SERVICE_DEREGISTER. If this bit
flag is one, and it is valid, the name-space provider updates any relevant
persistent store information when the operation is performed. For
example: If the operation involves deregistration in a name space that uses a
persistent store, the name-space provider would remove the relevant
persistent store information. |
lpService_Info
Points to a SERVICE_INFO structure that contains
information about the network service or service type.
lpServiceAsyncInfo
This
parameter is reserved for future use. It must be set to NULL.
lpdwStatusFlags
A set of bit
flags that receive function status information. The following bit flag is
defined:
|
Value |
Meaning |
|
SET_SERVICE_PARTIAL_SUCCESS |
One or more
name-space providers were unable to successfully perform the requested
operation. |
Return Values
If the
function succeeds, the return value is not SOCKET_ERROR.
If the
function fails, the return value is SOCKET_ERROR. To get extended error
information, call GetLastError. GetLastError may return the following extended
error value:
|
Value |
Meaning |
|
ERROR_ALREADY_REGISTERED |
The
function tried to register a service that was already registered. |
See Also