Export (0) Print
Expand All
Expand Minimize

WS_LISTENER_PROPERTY_ID enumeration

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


enum WS_LISTENER_PROPERTY_ID {  WS_LISTENER_PROPERTY_LISTEN_BACKLOG, 
  WS_LISTENER_PROPERTY_IP_VERSION, 
  WS_LISTENER_PROPERTY_STATE, 
  WS_LISTENER_PROPERTY_ASYNC_CALLBACK_MODEL, 
  WS_LISTENER_PROPERTY_CHANNEL_TYPE, 
  WS_LISTENER_PROPERTY_CHANNEL_BINDING, 
  WS_LISTENER_PROPERTY_CONNECT_TIMEOUT, 
  WS_LISTENER_PROPERTY_IS_MULTICAST, 
  WS_LISTENER_PROPERTY_MULTICAST_INTERFACES, 
  WS_LISTENER_PROPERTY_MULTICAST_LOOPBACK, 
  WS_LISTENER_PROPERTY_CLOSE_TIMEOUT, 
  WS_LISTENER_PROPERTY_TO_HEADER_MATCHING_OPTIONS, 
  WS_LISTENER_PROPERTY_TRANSPORT_URL_MATCHING_OPTIONS, 
  WS_LISTENER_PROPERTY_CUSTOM_LISTENER_CALLBACKS, 
  WS_LISTENER_PROPERTY_CUSTOM_LISTENER_PARAMETERS, 
  WS_LISTENER_PROPERTY_CUSTOM_LISTENER_INSTANCE, 
  WS_LISTENER_PROPERTY_DISALLOWED_USER_AGENT 

};

Constants

WS_LISTENER_PROPERTY_LISTEN_BACKLOG

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

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

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

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

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

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

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

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

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

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

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

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:


WS_MATCH_URL_THIS_HOST |
WS_MATCH_URL_EXACT_PATH |
WS_MATCH_URL_PORT |
WS_MATCH_URL_NO_QUERY

WS_LISTENER_PROPERTY_TRANSPORT_URL_MATCHING_OPTIONS

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:


WS_MATCH_URL_THIS_HOST |
WS_MATCH_URL_EXACT_PATH |
WS_MATCH_URL_PORT |
WS_MATCH_URL_NO_QUERY

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

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

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, it's value is NULL and size is zero.

WS_LISTENER_PROPERTY_CUSTOM_LISTENER_INSTANCE

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

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

Minimum supported client

Windows 7 [desktop apps | Windows Store apps]

Minimum supported server

Windows Server 2008 R2 [desktop apps | Windows Store apps]

Header

WebServices.h

 

 

Community Additions

ADD
Show:
© 2014 Microsoft