Xlib provides two atom utility routines. XInternAtom returns an existing atom or (if the third argument is False) creates and returns an atom that matches the given string. XGetAtomName returns the string that matches the given atom.
Motif has a number of routines to help an application install protocol atoms and handle ClientMessages sent when the protocols are invoked. These routines maintain an internal registry of properties, protocol atoms associated with the properties, and callback routines associated with the protocol atoms. The application can use these routines with shells that are subclasses of VendorShell.
XmAddProtocols associates one or more protocol atoms with a property for a given shell. If the shell is realized, it adds those protocols to the property for the shell's window. If the shell is not realized, it arranges for the protocols to be added to the property and for a ClientMessage event handler to be added at the time the shell is realized. XmAddWMProtocols is a specialized version that adds protocols for the WM_PROTOCOLS property.
XmAddProtocolCallback adds a callback routine to a callback list associated with a protocol. It calls XmAddProtocols if the protocol has not yet been registered. When the protocol manager's ClientMessage event handler receives a ClientMessage for the protocol, it invokes the procedures on the associated callback list. The first argument to each callback procedure is the shell associated with the protocol. The second argument is the client data, if any, specified in the call to XmAddProtocolCallback. The third argument is a pointer to an XmAnyCallbackStruct structure whose reason member is XmCR_PROTOCOLS and whose event member is a pointer to the ClientMessage event. In the ClientMessage event, the message_type member is the property that contains the protocol, the format member is 32, and the data.l[0] member is the protocol atom. XmAddWMProtocolCallback is a specialized version of XmAddProtocolCallback that adds a callback for a protocol on the WM_PROTOCOLS property.
An application can also use XmSetProtocolHooks to specify a routine to be called before or after a callback list is invoked for a protocol. XmSetWMProtocolHooks is a specialized version that adds prehooks and posthooks for a protocol on the WM_PROTOCOLS property.
Once an application has registered a protocol and optional callback routines, it can make the protocol active or inactive. A protocol is active if it has been added to the associated property for the window. A protocol is inactive if it has been removed from the associated property. XmActivateProtocol makes a registered protocol active, and XmDeactivateProtocol makes a protocol inactive. XmActivateWMProtocol and XmDeactivateWMProtocol are specialized versions that activate or inactivate a protocol on the WM_PROTOCOLS property.
XmRemoveProtocolCallback removes a callback routine from the callback list associated with the protocol. XmRemoveProtocols removes one or more protocols and all callbacks associated with those protocols from the internal registry. If the shell is realized, it removes those protocols from the associated property. XmRemoveWMProtocolCallback and XmRemoveWMProtocols are specialized versions that remove callbacks or protocols for the WM_PROTOCOLS property.