Edit

WS_LISTENER_PROPERTY_ID enumeration (webservices.h)

  • Article

Each listener property is of type WS_LISTENER_PROPERTY, is identified by an ID, and has an associated value. If a property is not specified when the listener is created, then its default value is used.

Syntax

typedef enum {
  WS_LISTENER_PROPERTY_LISTEN_BACKLOG = 0,
  WS_LISTENER_PROPERTY_IP_VERSION = 1,
  WS_LISTENER_PROPERTY_STATE = 2,
  WS_LISTENER_PROPERTY_ASYNC_CALLBACK_MODEL = 3,
  WS_LISTENER_PROPERTY_CHANNEL_TYPE = 4,
  WS_LISTENER_PROPERTY_CHANNEL_BINDING = 5,
  WS_LISTENER_PROPERTY_CONNECT_TIMEOUT = 6,
  WS_LISTENER_PROPERTY_IS_MULTICAST = 7,
  WS_LISTENER_PROPERTY_MULTICAST_INTERFACES = 8,
  WS_LISTENER_PROPERTY_MULTICAST_LOOPBACK = 9,
  WS_LISTENER_PROPERTY_CLOSE_TIMEOUT = 10,
  WS_LISTENER_PROPERTY_TO_HEADER_MATCHING_OPTIONS = 11,
  WS_LISTENER_PROPERTY_TRANSPORT_URL_MATCHING_OPTIONS = 12,
  WS_LISTENER_PROPERTY_CUSTOM_LISTENER_CALLBACKS = 13,
  WS_LISTENER_PROPERTY_CUSTOM_LISTENER_PARAMETERS = 14,
  WS_LISTENER_PROPERTY_CUSTOM_LISTENER_INSTANCE = 15,
  WS_LISTENER_PROPERTY_DISALLOWED_USER_AGENT = 16
} WS_LISTENER_PROPERTY_ID;

Constants

 
WS_LISTENER_PROPERTY_LISTEN_BACKLOG
Value: 0
Used with WsCreateListener or WsGetListenerProperty for WS_TCP_CHANNEL_BINDING.


The accompanying value member of the WS_LISTENER_PROPERTY structure is a ULONG.

This controls the maximum length of the queue of pending connections. If set to
SOMAXCONN, the backlog will be set to a maximum reasonable value.
WS_LISTENER_PROPERTY_IP_VERSION
Value: 1
Used with WsCreateListener or WsGetListenerProperty for WS_TCP_CHANNEL_BINDING or WS_UDP_CHANNEL_BINDING.


The accompanying value member of the WS_LISTENER_PROPERTY structure is an WS_IP_VERSION value.

This property specifies which IP version that the listener should use.


The default value is WS_IP_VERSION_AUTO.
WS_LISTENER_PROPERTY_STATE
Value: 2
Used with WsGetListenerProperty for all channel types.



The accompanying value member of the WS_LISTENER_PROPERTY structure is a WS_LISTENER_STATE value.

Returns the current WS_LISTENER_STATE of the listener. The returned value is a snapshot of the current state, so it is
possible that the state may have changed before the caller has
had a chance to examine the value.
WS_LISTENER_PROPERTY_ASYNC_CALLBACK_MODEL
Value: 3
Used with WsCreateListener or WsGetListenerProperty for all channel types.


The accompanying value member of the WS_LISTENER_PROPERTY structure is a WS_CALLBACK_MODEL value.

This value indicates the preferred async callback model when issuing
async operations for the listener or channels that are created for it
using WsCreateChannelForListener.


The default is WS_LONG_CALLBACK.


The WS_SERVICE_HOST only supports WS_LONG_CALLBACK as an acceptable value
for this property.
WS_LISTENER_PROPERTY_CHANNEL_TYPE
Value: 4
Used with WsGetListenerProperty for all channel types.

The accompanying value member of the WS_LISTENER_PROPERTY structure is a WS_CHANNEL_TYPE value.

This property
specifies the message exchange pattern of the channel being used.
WS_LISTENER_PROPERTY_CHANNEL_BINDING
Value: 5
Used with WsGetListenerProperty for all channel types.

The accompanying value member of the WS_LISTENER_PROPERTY structure is a WS_CHANNEL_BINDING value.

This property
specifies the binding of the channel being used.
WS_LISTENER_PROPERTY_CONNECT_TIMEOUT
Value: 6
Used with WsCreateListener or WsGetListenerProperty for WS_TCP_CHANNEL_BINDING and WS_NAMEDPIPE_CHANNEL_BINDING.

The accompanying value member of the WS_LISTENER_PROPERTY structure is a ULONG.

An accept operation will wait
for an infinite amount of time to accept the underlying TCP socket or named pipe. This
timeout corresponds to the amount of time dedicated to the net.tcp or net.pipe handshake
that takes place between the client and service once the client connects.
The timeout value is in milliseconds, where the value INFINITE indicates
no timeout. Use the
WS_CHANNEL_PROPERTY_CONNECT_TIMEOUT to set the corresponding
value on the client side.


The default value is 15000 (15 seconds).
WS_LISTENER_PROPERTY_IS_MULTICAST
Value: 7
Used with WsCreateListener or WsGetListenerProperty for WS_UDP_CHANNEL_BINDING with WS_CHANNEL_TYPE_DUPLEX to indicate that the listener is listening on a multicast address.


The accompanying value member of the WS_LISTENER_PROPERTY structure is a BOOL.

Note that setting this property is not sufficient when listening on
a multicast address. The set of interfaces must also be specified
using the WS_LISTENER_PROPERTY_MULTICAST_INTERFACES property.


The channel does not validate that the address is in fact a
a multicast address, but it sets the reuse of the socket
such that another process can also open the same port.


The default value is FALSE.
WS_LISTENER_PROPERTY_MULTICAST_INTERFACES
Value: 8
Used with WsCreateListener or WsSetListenerProperty for WS_UDP_CHANNEL_BINDING with WS_CHANNEL_TYPE_DUPLEX.


The accompanying value member of the WS_LISTENER_PROPERTY structure is an array of ULONG values.

The size of the property
is sizeof(ULONG) multiplied by the number of values. Each value represents
the interface index of an adapter. The indices of adapters can be
obtained using the GetAdaptersAddresses function.


This value of the WS_LISTENER_PROPERTY_IS_MULTICAST
property must be TRUE in order to use this property.


The default value is an empty list (no interfaces).
WS_LISTENER_PROPERTY_MULTICAST_LOOPBACK
Value: 9
Used with WsCreateListener for WS_UDP_CHANNEL_BINDING
with WS_CHANNEL_TYPE_DUPLEX.


The accompanying value member of the WS_LISTENER_PROPERTY structure is a BOOL.

This indicates whether or not messages
sent on the loopback interface are received by this channel. If TRUE,
then messages are received (otherwise, they will not be seen by the channel).


This value of the WS_LISTENER_PROPERTY_IS_MULTICAST
property must be TRUE in order to use this property.


The default value is TRUE.
WS_LISTENER_PROPERTY_CLOSE_TIMEOUT
Value: 10
Used with WsCreateListener or WsGetListenerProperty for WS_HTTP_CHANNEL_BINDING with WS_CHANNEL_TYPE_REPLY.


The accompanying value member of the WS_LISTENER_PROPERTY structure is a ULONG.

This indicates the number of milliseconds to
wait for clients to receive data from responses when WsCloseListener is called.


The purpose of this timeout is to allow clients time to continue receiving
data from HTTP responses sent by the server before the HTTP server disconnects
the client connections.


The calculation of the timeout value used is as follows:



  • At the time that WsCloseListener is called, determine the
    time the last response was sent (the last response time). For the purposes of
    this timeout calculation, a response is recorded as sent once WsWriteMessageEnd has been called for the response.

  • Calculate the difference between the current time and the last response time.

  • If the difference is more than the timeout value, then the actual
    timeout used is zero.

  • If the difference is less than or equal to the timeout value, then the
    actual timeout used is the timeout value minus the difference.


The default timeout value is 5000 (5 seconds).
WS_LISTENER_PROPERTY_TO_HEADER_MATCHING_OPTIONS
Value: 11
Used with WsCreateListener for WS_TCP_CHANNEL_BINDING,
WS_HTTP_CHANNEL_BINDING, WS_UDP_CHANNEL_BINDING, or WS_NAMEDPIPE_CHANNEL_BINDING.


The accompanying value member of the WS_LISTENER_PROPERTY structure is a ULONG.

The property value contains a set of flags (see WS_URL_MATCHING_OPTIONS) which
specify how to match the URL in the WS_TO_HEADER of any received messages.


The default value is:



syntax<br><br>WS_MATCH_URL_THIS_HOST |<br>WS_MATCH_URL_EXACT_PATH |<br>WS_MATCH_URL_PORT |<br>WS_MATCH_URL_NO_QUERY<br><br>
WS_LISTENER_PROPERTY_TRANSPORT_URL_MATCHING_OPTIONS
Value: 12
Used with WsCreateListener for WS_TCP_CHANNEL_BINDING or
WS_HTTP_CHANNEL_BINDING.


The accompanying value member of the WS_LISTENER_PROPERTY structure is a ULONG.

The property value contains a set of flags (see WS_URL_MATCHING_OPTIONS) which
specify how to match the transport URL of any accepted channels. See
WS_CHANNEL_PROPERTY_TRANSPORT_URL for more information on the transport URL.


The default value is:



syntax<br><br>WS_MATCH_URL_THIS_HOST |<br>WS_MATCH_URL_EXACT_PATH |<br>WS_MATCH_URL_PORT |<br>WS_MATCH_URL_NO_QUERY<br><br>

This property only controls the verification of the message once it has been received
by the process, not the routing of the message to the process (which is determined
by the URL passed to WsOpenListener).
WS_LISTENER_PROPERTY_CUSTOM_LISTENER_CALLBACKS
Value: 13
Used with WsCreateListener for WS_CUSTOM_CHANNEL_BINDING.


The accompanying value member of the WS_LISTENER_PROPERTY structure is a WS_CUSTOM_LISTENER_CALLBACKS structure.

This property is used to specify callbacks that
define the implementation of a custom listener.


This property must be specified when WS_CUSTOM_CHANNEL_BINDING is used.
WS_LISTENER_PROPERTY_CUSTOM_LISTENER_PARAMETERS
Value: 14
Used with WsCreateListener for WS_CUSTOM_CHANNEL_BINDING.


The accompanying value member of the WS_LISTENER_PROPERTY structure is a pointer to an arbitrary sized data type.
The size of the property is the size of the data type.


This property is used to specify parameters used to create the custom
listener implementation.


The value of this property will be passed to the
WS_CREATE_LISTENER_CALLBACK.


If this property is not specified, its value is NULL and size is zero.
WS_LISTENER_PROPERTY_CUSTOM_LISTENER_INSTANCE
Value: 15
Used with WsGetChannelProperty for WS_CUSTOM_CHANNEL_BINDING.


The accompanying value member of the WS_LISTENER_PROPERTY structure is a void* and size the property is sizeof(void*).

The value
corresponds to the listenerInstance value returned by the
WS_CREATE_LISTENER_CALLBACK.


This property can be used to obtain the underlying listener
instance for a custom listener. This allows a caller to directly
interact with the instance for cases when the existing
set of listener properties or listener functions is insufficient.
WS_LISTENER_PROPERTY_DISALLOWED_USER_AGENT
Value: 16
Used with WsCreateListener for WS_HTTP_CHANNEL_BINDING.


The accompanying value member of the WS_LISTENER_PROPERTY structure is a pointer to WS_DISALLOWED_USER_AGENT_SUBSTRINGS which specifies the list of disallowed user
agents sub-strings.

  • Upon receiving the HTTP request, the UserAgent header value is extracted.

  • Each sub-string in the list, is searched in the extracted UserAgent string value.

  • If the substring is found the request is rejected.




The list by default contains the following entry

  • Web Browser(s): Mozilla




This property does not apply to listeners configured with WS_ENCODING_RAW encoding.

Requirements

Requirement Value
Minimum supported client Windows 7 [desktop apps | UWP apps]
Minimum supported server Windows Server 2008 R2 [desktop apps | UWP apps]
Header webservices.h