ChannelListen

ChannelListen[channel]

starts listening on the specified channel, executing the default handler function for that channel whenever a message is received.

ChannelListen[channel,func]

applies func to the association corresponding to each message received on the channel.

ChannelListen[channel,None]

stores each message received on the channel, without applying any function.

Details and Options

  • ChannelListen[] gives a ChannelListener object.
  • In ChannelListen[channel,], channel can be specified as a channel object or in any of the forms used inside ChannelObject.
  • With the default setting $AllowExternalChannelFunctions=False, ChannelListen[channel] works only for certified channels and for channels owned by you.
  • When allowed by the setting for $AllowExternalChannelFunctions, ChannelListen[channel] applies the "MessageReceived" function in the association given as the setting for the HandlerFunctions option of channel.
  • ChannelListen[channel] is equivalent to ChannelListen[channel,Automatic].
  • If specified in ChannelListen[channel,func], func overrides the "MessageReceived" handler of channel. It is called with the association containing the following elements:
  • "Message"contents of the message
    "MessageID"unique message ID
    "Timestamp"server time stamp for the message
    "RequesterAddress"IP address of the sender
    "RequesterWolframID"Wolfram ID of the sender
    "RequesterWolframUUID"Wolfram UUID of the sender
  • The contents of a message are given literally if the message is a string, number, True, False, Null, or a list or association of such objects. All other messages are given in the form HoldComplete[expr].
  • Messages containing rules in the form "key"value are given literally for any expression value.
  • For security reasons, you should exercise caution in accessing unevaluated message contents, such as parts of held expressions, right-hand sides of delayed rules, or applying ToExpression to string messages.
  • ChannelListen does not require an explicit channel to exist on the channel broker.
  • ChannelListen accepts the following options:
  • AutoRemoveFalsewhether to remove the listener after receiving one message
    ChannelDatabinNonedatabin in which to store messages
    NotificationFunctionInheritednotification to give when a message arrives
    PermissionsAutomaticpermissions for access
  • With the default setting NotificationFunctionInherited, the notification is inherited from the options for the channel.
  • For channels that exist on the channel broker server, a value of the Permissions option given to ChannelListen is ignored.
  • A channel listener set up by ChannelListen can be removed using RemoveChannelListener.
  • Removing a channel listener discards messages cached by the listener.
  • Terminating a Wolfram Language session removes all active channel listeners.

Examples

open allclose all

Basic Examples  (2)

Create a channel and start listening:

In[1]:=
Click for copyable input
Out[1]=
In[2]:=
Click for copyable input
Out[2]=

Send a message to the channel and retrieve the contents of the message from the listener:

In[3]:=
Click for copyable input
Out[3]=
In[4]:=
Click for copyable input
Out[4]=

Remove the listener and delete the channel:

In[5]:=
Click for copyable input
Out[5]=
In[6]:=
Click for copyable input
Out[6]=

Define a custom handler function that will be executed when a message arrives:

In[1]:=
Click for copyable input
Out[1]=

Sending a message to the channel causes the function to be called:

In[2]:=
Click for copyable input
Out[2]=

The message is also recorded in the ChannelListener object:

In[3]:=
Click for copyable input
Out[3]=

Remove the listener:

In[4]:=
Click for copyable input
Out[4]=

Scope  (12)

Options  (5)

Applications  (8)

Properties & Relations  (3)

Possible Issues  (1)

Neat Examples  (2)

See Also

ChannelSend  ChannelListener  RemoveChannelListener  ChannelListeners  ChannelSubscribers  CreateChannel

Introduced in 2016
(11.0)