#include "wsrmapi.h"

Include dependency graph for wsrmapi.c:

Functions
static int	soap_wsrm_init (struct soap soap, struct soap_wsrm_data data, void *arg)
	Initializes plugin data. More...

static int	soap_wsrm_copy (struct soap soap, struct soap_plugin p, struct soap_plugin *q)
	Copy plugin data (private thread data). More...

static void	soap_wsrm_delete (struct soap soap, struct soap_plugin p)
	Deletes plugin data. More...

static int	soap_wsrm_send (struct soap soap, const char buf, size_t len)
	Internal callback function to override fsend(). When the wsrm plugin is enabled, saves the message to the current sequence that is created at the client side. Allows unacknowledged messages to be resend with soap_wsrm_resend(). More...

static int	soap_wsrm_preparefinalrecv (struct soap *soap)
	Internal callback function to override fpreparefinalrecv(). Takes acks returned by response to update the states of the sequences with acknowledgements. Acknowledged messages do not have to be resend and are purged from the sequence states. Also checks if at client-side response message was already received and otherwise records it in the state. More...

static int	soap_wsrm_disconnect (struct soap *soap)
	Internal callback function to override fdisconnect(). Turns caching off, sets the cached message to NACK, and resets the server-side handle, so sequence can be deallocated later. More...

static int	soap_wsrm_process_ack (struct soap soap, struct _wsrm__SequenceAcknowledgement ack)
	Internal function to purge acknowledged messages as given by wsrm:SequenceAcknowledgement header. More...

static int	soap_wsrm_chk (struct soap *soap, int timeout, int flag)
	Receiver (server)-side check for the presence of WS-Addressing and WS-RM header blocks in the SOAP header, checks for protocol errors, and rejects duplicate messages. Also prepares the return WS-RM header. This function should be called in the each service operation that supports WS-RM. Do not use this function in a ReplyTo response-accepting destination service operation. More...

static int	soap_wsrm_chk_acks (struct soap *soap)
	Internal function to check for AckRequested headers to update state. More...

static int	soap_wsrm_add_acks (struct soap soap, struct soap_wsrm_sequence seq, ULONG64 nack, int all, int piggy)
	Internal function to add SequenceAcknowledgement headers for AckRequested. When piggy==0 or internal AcksTo destination is set, sends acknowledgements to the AcksTo destination service or back to the source related to the seq. These sends can take time, which can be controlled with the soap context connect_timeout, send_timeout, recv_timeout settings. More...

static int	soap_wsrm_set_ack (struct soap soap, ULONG64 nack, struct soap_wsrm_sequence seq, struct _wsrm__SequenceAcknowledgement *ack)
	Internal function called by soap_wsrm_add_acks() to populate the SequenceAcknowledgement header block. More...

static int	soap_wsrm_resend_seq (struct soap soap, struct soap_wsrm_sequence seq, int all, ULONG64 lower, ULONG64 upper)
	Internal function to resend unacknowledged messages of a sequence given a range of message numbers. Used by soap_wsrm_resend(). More...

static const char *	soap_wsrm_seq_newid (struct soap *soap)
	Internal function to generate a new sequence identifier. More...

static void	soap_wsrm_seq_insert_data (struct soap_wsrm_sequence *seq)
	Internal function to insert seq id in hash table for fast lookup. More...

static void	soap_wsrm_seq_delete_data (struct soap_wsrm_sequence *seq)
	Internal function to delete seq id from hash table. More...

static struct soap_wsrm_sequence *	soap_wsrm_seq_lookup_data (const char *id)
	Internal function to look up sequence given its id. More...

static void	soap_wsrm_seq_insert_ack (struct soap_wsrm_sequence *seq)
	Internal function to insert acksid for fast lookup. More...

static void	soap_wsrm_seq_delete_ack (struct soap_wsrm_sequence *seq)
	Internal function to delete acksid for fast lookup. More...

static struct soap_wsrm_sequence *	soap_wsrm_seq_lookup_ack (const char *id)
	Internal function to look up sequence given its acksid. More...

static struct soap_wsrm_sequence *	soap_wsrm_seq_insert (struct soap *soap)
	Internal function to create a new local sequence state. More...

static int	soap_wsrm_msg_append (struct soap soap, struct soap_wsrm_data data, const char *buf, size_t len)
	Internal function used by soap_wsrm_send() to append message data to the current message being transmitted in the current sequence. More...

static int	soap_wsrm_num_lookup (struct soap soap, const struct soap_wsrm_sequence seq, ULONG64 num)
	Internal function to look up a message number in the sequence state. More...

static int	soap_wsrm_num_insert (struct soap soap, struct soap_wsrm_sequence seq, ULONG64 num)
	Internal function to insert a message number in the sequence state. Updates the sequence ranges. More...

static int	soap_wsrm_num_size (const struct soap_wsrm_sequence *seq)
	Internal function returns the number of message ranges of the successfully received messages in a sequence state. More...

static void	soap_wsrm_num_free (struct soap soap, struct soap_wsrm_sequence seq)
	Internal function to deallocate all message number ranges from a sequence state. More...

static struct soap_wsrm_message *	soap_wsrm_msg_new (struct soap soap, struct soap_wsrm_sequence seq, ULONG64 num)
	Internal function to allocate a new message in a sequence, updates message count seq->num. More...

static void	soap_wsrm_msg_free (struct soap soap, struct soap_wsrm_message p)
	Internal function to deallocate all cached message content from a sequence state. More...

SOAP_FMAC1 int SOAP_FMAC2	soap_wsrm_create (struct soap soap, const char to, const char replyto, LONG64 expires, const char wsa_id, soap_wsrm_sequence_handle *seq)
	Creates a new sequence. Sequences are usually created by the sender (client) and confirmed by the receiver (server). The 'to' server address must be used for all messages of the sequence to be sent to the WS-RM destination server. Optionally the 'replyto' address can be given of the WS-RM source to reply to. A sequence ID is generated by the server upon success. More...

SOAP_FMAC1 int SOAP_FMAC2	soap_wsrm_create_offer (struct soap soap, const char to, const char replyto, const char id, LONG64 expires, enum wsrm__IncompleteSequenceBehaviorType behavior, const char wsa_id, soap_wsrm_sequence_handle seq)
	Creates a new sequence by offering suggested WS-RM parameters to the WS-RM destination. Sequences are usually created by the sender (client) and confirmed by the receiver (server). The 'to' server address must be used for all messages of the sequence to be sent to the WS-RM destination server. Optionally the 'replyto' address can be given of the WS-RM source to reply to. A sequence ID is generated by the server upon success. More...

SOAP_FMAC1 int SOAP_FMAC2	soap_wsrm_create_offer_acksto (struct soap soap, const char to, const char replyto, const char acksto, const char id, LONG64 expires, enum wsrm__IncompleteSequenceBehaviorType behavior, const char wsa_id, soap_wsrm_sequence_handle *seq)
	Creates a new sequence by offering suggested WS-RM parameters to the WS-RM destination. Sequences are usually created by the sender (client) and confirmed by the receiver (server). The 'to' server address must be used for all messages of the sequence to be sent to the WS-RM destination server. Optionally the 'replyto' address can be given of the WS-RM source to reply to and an 'acksto' address can be given for acknowledgement messages to be sent to (normally to the reply to). A sequence ID is generated by the server upon success. More...

SOAP_FMAC1 int SOAP_FMAC2	soap_wsrm_request_num (struct soap soap, soap_wsrm_sequence_handle seq, const char wsa_id, const char *wsa_action, ULONG64 num)
	Adds a WS-RM sequence message number to the next message transmitted. No acks are requested. More...

SOAP_FMAC1 int SOAP_FMAC2	soap_wsrm_request (struct soap soap, soap_wsrm_sequence_handle seq, const char wsa_id, const char *wsa_action)
	Adds a WS-RM sequence message number to the next message transmitted to the WS-RM destination and increments the message counter by one. No acks are requested. More...

SOAP_FMAC1 int SOAP_FMAC2	soap_wsrm_request_acks (struct soap soap, soap_wsrm_sequence_handle seq, const char wsa_id, const char *wsa_action)
	Adds a WS-RM sequence message number to the next message transmitted to the WS-RM destination and increments the message counter by one. Message acks for the current sequence are requested. More...

SOAP_FMAC1 int SOAP_FMAC2	soap_wsrm_check_retry (struct soap *soap, soap_wsrm_sequence_handle seq)
	Client-side check to verify if the remote call can be retried when a failure occured. Increases the robustness of messages sends, by ensuring that the message was at least transmitted (but not necessarily received). Also implements HTTP 307 Temporary Redirect. Retries are limited to SOAP_WSRM_MAX_RETRIES iterations. More...

SOAP_FMAC1 int SOAP_FMAC2	soap_wsrm_resend (struct soap *soap, soap_wsrm_sequence_handle seq, ULONG64 lower, ULONG64 upper)
	Resend all unacknowledged messages, i.e. messages that were automatically cached for this sequence. Messages stored in the sequence for retransmission (those that were previously sent but not acknowledged) are resent to the soap_wsrm_to() address (which was set by soap_wsrm_create() or soap_wsrm_create_offer(), or the ReplyTo address). It is recommended to resend messages after the last message in the sequence was transmitted before closing the sequence. To reduce unnecessary resend attempts, it is recommended to use soap_wsrm_request_ack() with the last message to request acks for messages already delivered. More...

SOAP_FMAC1 int SOAP_FMAC2	soap_wsrm_resend_only_nacked (struct soap *soap, soap_wsrm_sequence_handle seq, ULONG64 lower, ULONG64 upper)
	Resend all explicitly nack'ed messages indicaed by peer. Messages stored in the sequence for retransmission (those that were previously sent but not acknowledged) are resent to the soap_wsrm_to() address (which was set by soap_wsrm_create() or soap_wsrm_create_offer(), or the ReplyTo address). More...

SOAP_FMAC1 int SOAP_FMAC2	soap_wsrm_close (struct soap soap, soap_wsrm_sequence_handle seq, const char wsa_id)
	Closes the sequence, but does not yet terminate it. No new messages should be send, but messages can be resend with soap_wsrm_resend() if desired. More...

SOAP_FMAC1 int SOAP_FMAC2	soap_wsrm_terminate (struct soap soap, soap_wsrm_sequence_handle seq, const char wsa_id)
	Terminates the sequence. No new messages should be send and no resends should be tried. Usually done after soap_wsrm_close() or any time to terminate the sequence prematurely. More...

SOAP_FMAC1 int SOAP_FMAC2	soap_wsrm_pulse (struct soap *soap, int timeout)
	Sends acknowledgements for all open sessions to all peers. Must set send and recv timeouts to prevent blocking. More...

SOAP_FMAC1 int SOAP_FMAC2	soap_wsrm_acknowledgement (struct soap soap, soap_wsrm_sequence_handle seq, const char wsa_id)
	Sends acknowledgements for all message sequences that require an acknowledgement (ack requested by peer) More...

SOAP_FMAC1 int SOAP_FMAC2	soap_wsrm_non_acknowledgement (struct soap *soap, soap_wsrm_sequence_handle seq, ULONG64 nack)
	Sends nack non-acknowledgement for a message. More...

SOAP_FMAC1 void SOAP_FMAC2	soap_wsrm_seq_free (struct soap *soap, soap_wsrm_sequence_handle seq)
	Must be called to free the sequence allocated by soap_wsrm_create() or by soap_wsrm_create_offer(). Sequences created by soap_wsrm_create_offer return handles that are not automatically reclaimed by the engine. More...

SOAP_FMAC1 const char *SOAP_FMAC2	soap_wsrm_to (const soap_wsrm_sequence_handle seq)
	Returns the endpoint address of the destination service that serves the sequence. Initially set with soap_wsrm_create or soap_wsrm_create_offer. HTTP 307 Temporary Redirect can change the endpoint during the lifetime of a message sequence. Thus, this function returns the most recent endpoint binding that can be used to send message to the server endpoint. More...

SOAP_FMAC1 const char *SOAP_FMAC2	soap_wsrm_acksto (const soap_wsrm_sequence_handle seq)
	Returns the endpoint address of the AcksTo acknowledgement service that serves the sequence, when set with soap_wsrm_create() or soap_wsrm_create_offer() or NULL otherwise. HTTP 307 Temporary Redirect can change the endpoint during the lifetime of a message sequence. Thus, this function returns the most recent endpoint binding. More...

SOAP_FMAC1 ULONG64 SOAP_FMAC2	soap_wsrm_num (const soap_wsrm_sequence_handle seq)
	Returns the current message number of the sequence. More...

SOAP_FMAC1 ULONG64 SOAP_FMAC2	soap_wsrm_nack (const soap_wsrm_sequence_handle seq)
	Returns the number of non-acknowledged messages sent. More...

SOAP_FMAC1 int SOAP_FMAC2	soap_wsrm_check (struct soap *soap)
	Receiver (server)-side check for the presence of WS-Addressing and WS-RM header blocks in the SOAP header, checks for protocol errors, and rejects duplicate messages. Also prepares the return WS-RM header. This function should be called in the each service operation that supports WS-RM. Do not use this function in a ReplyTo response-accepting destination service operation. When NoDicards behavior is set, out of sequence messages will be discared until message sequence has resumed (requires peer resends). More...

SOAP_FMAC1 int SOAP_FMAC2	soap_wsrm_check_and_wait (struct soap *soap, int timeout)
	Receiver (server)-side check for the presence of WS-Addressing and WS-RM header blocks in the SOAP header, checks for protocol errors, and rejects duplicate messages. Also prepares the return WS-RM header. This function should be called in the each service operation that supports WS-RM. Do not use this function in a ReplyTo response-accepting destination service operation. More...

SOAP_FMAC1 int SOAP_FMAC2	soap_wsrm_check_send_empty_response (struct soap *soap)
	Receiver (server)-side check for the presence of WS-Addressing and WS-RM header blocks in the SOAP header, checks for protocol errors, and rejects duplicate messages. Also prepares the return WS-RM header. This function should be called in the each service operation that sends an empty response back (one-way messaging). The behavior is the same as soap_wsrm_check() followed by soap_send_empty_response(), but more efficient and prevents blocking. More...

SOAP_FMAC1 int SOAP_FMAC2	soap_wsrm_check_send_empty_response_and_wait (struct soap *soap, int timeout)
	Receiver (server)-side check for the presence of WS-Addressing and WS-RM header blocks in the SOAP header, checks for protocol errors, and rejects duplicate messages. Also prepares the return WS-RM header. This function should be called in the each service operation that sends an empty response back (one-way messaging). The behavior is the same as soap_wsrm_check() followed by soap_send_empty_response(), but more efficient and prevents blocking. More...

SOAP_FMAC1 int SOAP_FMAC2	soap_wsrm_reply_num (struct soap *soap, int flag)
	Prepares reply from service. When flag is set, adds a WS-RM sequence message number to the next message transmitted. No acks are requested. No WS-Addressing message relay. More...

SOAP_FMAC1 int SOAP_FMAC2	soap_wsrm_reply (struct soap soap, const char wsa_id, const char *wsa_action)
	Server-side server operation reply to be performed when the service operation returns. Server operations that support WS-Addressing and WS-RM must call this function to return normally (and/or allow the response message to be relayed as per WS-Addressing). More...

SOAP_FMAC1 int SOAP_FMAC2	soap_wsrm_reply_request_acks (struct soap soap, const char wsa_id, const char *wsa_action)
	Server-side server operation reply to be performed when the service operation returns. Message acks for the current sequence are requested, but only when client made a create sequence offer. Server operations that support WS-Addressing and WS-RM must call this function or call soap_wsrm_reply() to return normally (and/or allow the response message to be relayed as per WS-Addressing). More...

SOAP_FMAC1 void SOAP_FMAC2	soap_wsrm_cleanup (struct soap *soap)
	Cleans up all expired sequences and releases resources. To be used at the server side to periodically clean up WS-RM sequences. Server-side cleanup is automatic, as long as WS-RM is in use. Does not release client-side sequences allocated by soap_wsrm_create() or soap_wsrm_create_offer(). More...

SOAP_FMAC5 int SOAP_FMAC6	__wsrm__CreateSequence (struct soap soap, struct wsrm__CreateSequenceType req, struct wsrm__CreateSequenceResponseType *res)
	WS-RM CreateSequence service operation. Automatically invoked by the server to process a create sequence request (with or without offer). Creates a new local sequence state to keep track of messages. More...

SOAP_FMAC5 int SOAP_FMAC6	__wsrm__CreateSequenceResponse (struct soap soap, struct wsrm__CreateSequenceResponseType res)
	WS-RM CreateSequenceResponse one-way service operation. Automatically invoked by the server to process a create sequence response (with or without offer). Creates a new local sequence state to keep track of messages. More...

SOAP_FMAC5 int SOAP_FMAC6	__wsrm__CloseSequence (struct soap soap, struct wsrm__CloseSequenceType req, struct wsrm__CloseSequenceResponseType *res)
	WS-RM CloseSequence service operation. Automatically invoked by the server to process the close sequence request. Updates the server's local sequence state to closed. More...

SOAP_FMAC5 int SOAP_FMAC6	__wsrm__CloseSequenceResponse (struct soap soap, struct wsrm__CloseSequenceResponseType res)
	WS-RM CloseSequenceResponse one-way service operation. Automatically invoked by the server to process the close sequence response. Updates the server's local sequence state to closed. More...

SOAP_FMAC5 int SOAP_FMAC6	__wsrm__TerminateSequence (struct soap soap, struct wsrm__TerminateSequenceType req, struct wsrm__TerminateSequenceResponseType *res)
	WS-RM TerminateSequence service operation. Automatically invoked by the server to process the terminate sequence request. Updates the server's local sequence state to terminated. More...

SOAP_FMAC5 int SOAP_FMAC6	__wsrm__TerminateSequenceResponse (struct soap soap, struct wsrm__TerminateSequenceResponseType res)
	WS-RM TerminateSequenceResponse one-way service operation. Automatically invoked by the server to process the terminate sequence response. Updates the server's local sequence state to terminated. More...

SOAP_FMAC5 int SOAP_FMAC6	__wsrm__SequenceAcknowledgement (struct soap *soap)
	WS-RM SequenceAcknowledgement operation. More...

SOAP_FMAC5 int SOAP_FMAC6	__wsrm__AckRequested (struct soap *soap)
	WS-RM AckRequested operation. More...

SOAP_FMAC5 int SOAP_FMAC6	__wsrm__LastMessage (struct soap *soap)
	WS-RM LastMessage operation (WS-RM 1.0). More...

SOAP_FMAC1 int SOAP_FMAC2	soap_wsrm_fault_subcode (struct soap soap, int flag, const char faultsubcode, const char faultstring, const char faultdetail)
	Sets sender/receiver SOAP Fault (sub)code for server faults (can be user defined faults). When called before soap_wsrm_check() in the server operation, terminates the current sequence. Otherwise, the sequence is not terminated. In either case the fault is returned to sender (client) or to the FaultTo server when the WS-Addressing FaultTo header was set by the sender. More...

SOAP_FMAC1 int SOAP_FMAC2	soap_wsrm_sender_fault_subcode (struct soap soap, const char faultsubcode, const char faultstring, const char faultdetail)
	Sets sender SOAP Fault (sub)code for server faults (can be user defined faults). When called before soap_wsrm_check() in the server operation, terminates the current sequence. Otherwise, the sequence is not terminated. In either case the fault is returned to sender (client) or to the FaultTo server when the WS-Addressing FaultTo header was set by the sender. More...

SOAP_FMAC1 int SOAP_FMAC2	soap_wsrm_receiver_fault_subcode (struct soap soap, const char faultsubcode, const char faultstring, const char faultdetail)
	Sets receiver SOAP Fault (sub)code for server faults (can be user defined faults). When called before soap_wsrm_check() in the server operation, terminates the current sequence. Otherwise, the sequence is not terminated. In either case the fault is returned to sender (client) or to the FaultTo server when the WS-Addressing FaultTo header was set by the sender. More...

SOAP_FMAC1 int SOAP_FMAC2	soap_wsrm_sender_fault (struct soap soap, const char faultstring, const char *faultdetail)
	Sets sender SOAP Fault for server faults (can be user defined faults). When called before soap_wsrm_check() in the server operation, terminates the current sequence. Otherwise, the sequence is not terminated. In either case the fault is returned to sender (client) or to the FaultTo server when the WS-Addressing FaultTo header was set by the sender. More...

SOAP_FMAC1 int SOAP_FMAC2	soap_wsrm_receiver_fault (struct soap soap, const char faultstring, const char *faultdetail)
	Sets receiver SOAP Fault for server faults (can be user defined faults). When called before soap_wsrm_check() in the server operation, terminates the current sequence. Otherwise, the sequence is not terminated. In either case the fault is returned to sender (client) or to the FaultTo server when the WS-Addressing FaultTo header was set by the sender. More...

SOAP_FMAC1 int SOAP_FMAC2	soap_wsrm_check_fault (struct soap soap, enum wsrm__FaultCodes fault, const char **info)
	Checks the presence of a WS-RM fault at the client side (or in the FaultTo destination service) when a response is received. More...

SOAP_FMAC1 int SOAP_FMAC2	soap_wsrm_error (struct soap soap, struct soap_wsrm_sequence seq, enum wsrm__FaultCodes fault)
	Sets SOAP Fault (sub)code for server WS-RM fault response. Terminates the sequence. More...

SOAP_FMAC1 void SOAP_FMAC2	soap_wsrm_dump (struct soap soap, FILE fd)
	Dumps the current sequences and details of the wsrm plugin for diagnotics purposes. More...

SOAP_FMAC1 int SOAP_FMAC2	soap_wsrm (struct soap soap, struct soap_plugin p, void *arg)
	Plugin registry function, used with soap_register_plugin. More...

SOAP_FMAC1 struct soap_wsrm_sequence *SOAP_FMAC2	soap_wsrm_seq_lookup_id (struct soap soap, const char id)
	Function to look up sequence given its id. More...

SOAP_FMAC1 struct soap_wsrm_sequence *SOAP_FMAC2	soap_wsrm_seq_lookup (struct soap soap, const char id)
	Function to look up sequence given its id. More...

SOAP_FMAC1 struct soap_wsrm_sequence *SOAP_FMAC2	soap_wsrm_seq (struct soap *soap)
	Assuming a SOAP header is received, gets the sequence associated with the message. More...

SOAP_FMAC1 void SOAP_FMAC2	soap_wsrm_seq_release (struct soap soap, struct soap_wsrm_sequence seq)
	Releases handle. More...

SOAP_FMAC1 int SOAP_FMAC2	soap_wsrm_seq_created (struct soap soap, struct soap_wsrm_sequence seq)
	Function to check if a sequence is created. More...

SOAP_FMAC1 int SOAP_FMAC2	soap_wsrm_seq_valid (struct soap soap, struct soap_wsrm_sequence seq)
	Function to check if a sequence is not valid, terminated, or needs to be terminated when expired. More...

SOAP_FMAC1 ULONG64 SOAP_FMAC2	soap_wsrm_msgs (const soap_wsrm_sequence_handle seq)
	Returns the number of complete messages received, or 0 when there is a gap. More...

SOAP_FMAC1 ULONG64 SOAP_FMAC2	soap_wsrm_recvnum (const soap_wsrm_sequence_handle seq)
	Returns the message number of last message received. More...

SOAP_FMAC1 ULONG64 SOAP_FMAC2	soap_wsrm_lastnum (const soap_wsrm_sequence_handle seq)
	Returns the last message number upon sequence close or 0. More...

Variables
const char	soap_wsrm_id [] = SOAP_WSRM_ID

static struct soap_wsrm_sequence *	soap_wsrm_session = NULL

char	soap_wsrm_idname [40] = ""

int	soap_wsrm_idnum = 0

static MUTEX_TYPE	soap_wsrm_session_lock = MUTEX_INITIALIZER

Function Documentation

SOAP_FMAC5 int SOAP_FMAC6 __wsrm__AckRequested ( struct soap * soap )

WS-RM AckRequested operation.

Parameters

soap context

Returns: SOAP_OK or error code

SOAP_FMAC5 int SOAP_FMAC6 __wsrm__CloseSequence	(	struct soap *	soap,
		struct wsrm__CloseSequenceType *	req,
		struct wsrm__CloseSequenceResponseType *	res
	)

WS-RM CloseSequence service operation. Automatically invoked by the server to process the close sequence request. Updates the server's local sequence state to closed.

Parameters

	soap	context
[in]	req	wsrm__CloseSequence request message
[out]	res	wsrm__CloseSequenceResponse response message

Returns: SOAP_OK or error code

SOAP_FMAC5 int SOAP_FMAC6 __wsrm__CloseSequenceResponse	(	struct soap *	soap,
		struct wsrm__CloseSequenceResponseType *	res
	)

WS-RM CloseSequenceResponse one-way service operation. Automatically invoked by the server to process the close sequence response. Updates the server's local sequence state to closed.

Parameters

	soap	context
[in]	res	wsrm__CloseSequenceResponse response message

Returns: SOAP_OK or error code

SOAP_FMAC5 int SOAP_FMAC6 __wsrm__CreateSequence	(	struct soap *	soap,
		struct wsrm__CreateSequenceType *	req,
		struct wsrm__CreateSequenceResponseType *	res
	)

WS-RM CreateSequence service operation. Automatically invoked by the server to process a create sequence request (with or without offer). Creates a new local sequence state to keep track of messages.

Parameters

	soap	context
[in]	req	wsrm__CreateSequence request message
[out]	res	wsrm__CreateSequenceResponse response message

Returns: SOAP_OK or error code

SOAP_FMAC5 int SOAP_FMAC6 __wsrm__CreateSequenceResponse	(	struct soap *	soap,
		struct wsrm__CreateSequenceResponseType *	res
	)

WS-RM CreateSequenceResponse one-way service operation. Automatically invoked by the server to process a create sequence response (with or without offer). Creates a new local sequence state to keep track of messages.

Parameters

	soap	context
[in]	res	wsrm__CreateSequenceResponse response message

Returns: SOAP_OK or error code

SOAP_FMAC5 int SOAP_FMAC6 __wsrm__LastMessage ( struct soap * soap )

WS-RM LastMessage operation (WS-RM 1.0).

Parameters

soap context

Returns: SOAP_OK or error code

SOAP_FMAC5 int SOAP_FMAC6 __wsrm__SequenceAcknowledgement ( struct soap * soap )

WS-RM SequenceAcknowledgement operation.

Parameters

soap context

Returns: SOAP_OK or error code

SOAP_FMAC5 int SOAP_FMAC6 __wsrm__TerminateSequence	(	struct soap *	soap,
		struct wsrm__TerminateSequenceType *	req,
		struct wsrm__TerminateSequenceResponseType *	res
	)

WS-RM TerminateSequence service operation. Automatically invoked by the server to process the terminate sequence request. Updates the server's local sequence state to terminated.

Parameters

	soap	context
[in]	req	wsrm__TerminateSequence request message
[out]	res	wsrm__TerminateSequenceResponse response message

Returns: SOAP_OK or error code

SOAP_FMAC5 int SOAP_FMAC6 __wsrm__TerminateSequenceResponse	(	struct soap *	soap,
		struct wsrm__TerminateSequenceResponseType *	res
	)

WS-RM TerminateSequenceResponse one-way service operation. Automatically invoked by the server to process the terminate sequence response. Updates the server's local sequence state to terminated.

Parameters

	soap	context
[in]	res	wsrm__TerminateSequenceResponse response message

Returns: SOAP_OK or error code

SOAP_FMAC1 int SOAP_FMAC2 soap_wsrm	(	struct soap *	soap,
		struct soap_plugin *	p,
		void *	arg
	)

Plugin registry function, used with soap_register_plugin.

Parameters

	soap	context
[in,out]	p	plugin created in registry
[in]	arg	optional argument passed from soap_register_plugin_arg

Returns: SOAP_OK

SOAP_FMAC1 int SOAP_FMAC2 soap_wsrm_acknowledgement	(	struct soap *	soap,
		soap_wsrm_sequence_handle	seq,
		const char *	wsa_id
	)

Sends acknowledgements for all message sequences that require an acknowledgement (ack requested by peer)

Parameters

	soap	context
	seq	sequence handle set by soap_wsrm_create or soap_wsrm_create_offer
[in]	wsa_id	WS-Addressing message ID (deprecated, not used)

Returns: SOAP_OK or error code

SOAP_FMAC1 const char* SOAP_FMAC2 soap_wsrm_acksto ( const soap_wsrm_sequence_handle seq )

Returns the endpoint address of the AcksTo acknowledgement service that serves the sequence, when set with soap_wsrm_create() or soap_wsrm_create_offer() or NULL otherwise. HTTP 307 Temporary Redirect can change the endpoint during the lifetime of a message sequence. Thus, this function returns the most recent endpoint binding.

Parameters

seq	sequence handle set by soap_wsrm_create() or soap_wsrm_create_offer()

Returns: the sequence endpoint address

static int soap_wsrm_add_acks	(	struct soap *	soap,
		struct soap_wsrm_sequence *	seq,
		ULONG64	nack,
		int	all,
		int	piggy
	)

static

Internal function to add SequenceAcknowledgement headers for AckRequested. When piggy==0 or internal AcksTo destination is set, sends acknowledgements to the AcksTo destination service or back to the source related to the seq. These sends can take time, which can be controlled with the soap context connect_timeout, send_timeout, recv_timeout settings.

Parameters

	soap	context
[in]	seq	pointer to sequence
[in]	nack	num of nack message, 0 to generate acks
[in]	all	when true always include all acks
[in]	piggy	when true add acks to message to be send

Returns: SOAP_OK or error code

SOAP_FMAC1 int SOAP_FMAC2 soap_wsrm_check ( struct soap * soap )

Receiver (server)-side check for the presence of WS-Addressing and WS-RM header blocks in the SOAP header, checks for protocol errors, and rejects duplicate messages. Also prepares the return WS-RM header. This function should be called in the each service operation that supports WS-RM. Do not use this function in a ReplyTo response-accepting destination service operation. When NoDicards behavior is set, out of sequence messages will be discared until message sequence has resumed (requires peer resends).

Parameters

soap context

Returns: SOAP_OK or SOAP_STOP (duplicate message error, MUST be returned by the service operation executing the soap_wsrm_check) or an error code.

SOAP_FMAC1 int SOAP_FMAC2 soap_wsrm_check_and_wait	(	struct soap *	soap,
		int	timeout
	)

Receiver (server)-side check for the presence of WS-Addressing and WS-RM header blocks in the SOAP header, checks for protocol errors, and rejects duplicate messages. Also prepares the return WS-RM header. This function should be called in the each service operation that supports WS-RM. Do not use this function in a ReplyTo response-accepting destination service operation.

Parameters

soap	context
timeout	NoDiscard behavior: 0=discard messages out of sequence to immediately resume, >0 wait (in seconds) until message sequence has resumed while sending Nacks every second to indicate messages are required to continue the flow of messages, <0 wait (in microseconds) until message sequence has resumed, send one nack when timeout occurred.

Returns: SOAP_OK or SOAP_STOP (duplicate message error, MUST be returned by the service operation executing the soap_wsrm_check) or an error code.

SOAP_FMAC1 int SOAP_FMAC2 soap_wsrm_check_fault	(	struct soap *	soap,
		enum wsrm__FaultCodes *	fault,
		const char **	info
	)

Checks the presence of a WS-RM fault at the client side (or in the FaultTo destination service) when a response is received.

Parameters

	soap	context
[out]	fault	code
[out]	info	string pointer related to the fault (or NULL)

Returns: SOAP_OK (no fault or not a WS-RM fault) or error when not WS-RM fault

SOAP_FMAC1 int SOAP_FMAC2 soap_wsrm_check_retry	(	struct soap *	soap,
		soap_wsrm_sequence_handle	seq
	)

Client-side check to verify if the remote call can be retried when a failure occured. Increases the robustness of messages sends, by ensuring that the message was at least transmitted (but not necessarily received). Also implements HTTP 307 Temporary Redirect. Retries are limited to SOAP_WSRM_MAX_RETRIES iterations.

Parameters

soap	context
seq	sequence handle set by soap_wsrm_create or soap_wsrm_create_offer

Returns: SOAP_OK when retry is safe, error code otherwise

SOAP_FMAC1 int SOAP_FMAC2 soap_wsrm_check_send_empty_response ( struct soap * soap )

Receiver (server)-side check for the presence of WS-Addressing and WS-RM header blocks in the SOAP header, checks for protocol errors, and rejects duplicate messages. Also prepares the return WS-RM header. This function should be called in the each service operation that sends an empty response back (one-way messaging). The behavior is the same as soap_wsrm_check() followed by soap_send_empty_response(), but more efficient and prevents blocking.

Parameters

soap context

Returns: SOAP_OK or SOAP_STOP (duplicate message error, MUST be returned by the service operation executing the soap_wsrm_check) or an error code.

SOAP_FMAC1 int SOAP_FMAC2 soap_wsrm_check_send_empty_response_and_wait	(	struct soap *	soap,
		int	timeout
	)

Receiver (server)-side check for the presence of WS-Addressing and WS-RM header blocks in the SOAP header, checks for protocol errors, and rejects duplicate messages. Also prepares the return WS-RM header. This function should be called in the each service operation that sends an empty response back (one-way messaging). The behavior is the same as soap_wsrm_check() followed by soap_send_empty_response(), but more efficient and prevents blocking.

Parameters

soap	context
timeout	NoDiscard behavior: 0=discard messages out of sequence to immediately resume, >0 wait (in seconds) until message sequence has resumed while sending Nacks every second to indicate messages are required to continue the flow of messages, <0 wait (in microseconds) until message sequence has resumed, send one nack when timeout occurred.

Returns: SOAP_OK or SOAP_STOP (duplicate message error, MUST be returned by the service operation executing the soap_wsrm_check) or an error code.

static int soap_wsrm_chk	(	struct soap *	soap,
		int	timeout,
		int	flag
	)

static

Receiver (server)-side check for the presence of WS-Addressing and WS-RM header blocks in the SOAP header, checks for protocol errors, and rejects duplicate messages. Also prepares the return WS-RM header. This function should be called in the each service operation that supports WS-RM. Do not use this function in a ReplyTo response-accepting destination service operation.

Parameters

soap	context
timeout	NoDiscard behavior: 0=discard messages out of sequence to immediately resume, >0 wait (in seconds) until message sequence has resumed while sending Nacks every second to indicate messages are required to continue the flow of messages, <0 wait (in microseconds) until message sequence has resumed, send one nack when timeout occurred.
flag	0=no response, 1=send empty response

Returns: SOAP_OK or SOAP_STOP (duplicate message error, MUST be returned by the service operation executing the soap_wsrm_check) or an error code.

static int soap_wsrm_chk_acks ( struct soap * soap )

static

Internal function to check for AckRequested headers to update state.

Parameters

soap context

Returns: SOAP_OK or error code

SOAP_FMAC1 void SOAP_FMAC2 soap_wsrm_cleanup ( struct soap * soap )

Cleans up all expired sequences and releases resources. To be used at the server side to periodically clean up WS-RM sequences. Server-side cleanup is automatic, as long as WS-RM is in use. Does not release client-side sequences allocated by soap_wsrm_create() or soap_wsrm_create_offer().

Parameters

soap context

SOAP_FMAC1 int SOAP_FMAC2 soap_wsrm_close	(	struct soap *	soap,
		soap_wsrm_sequence_handle	seq,
		const char *	wsa_id
	)

Closes the sequence, but does not yet terminate it. No new messages should be send, but messages can be resend with soap_wsrm_resend() if desired.

Parameters

	soap	context
	seq	sequence handle set by soap_wsrm_create or soap_wsrm_create_offer
[in]	wsa_id	WS-Addressing message ID (optional)

Returns: SOAP_OK or error code

static int soap_wsrm_copy	(	struct soap *	soap,
		struct soap_plugin *	p,
		struct soap_plugin *	q
	)

static

Copy plugin data (private thread data).

Parameters

	soap	context
[out]	p	plugin
[in]	q	plugin

Returns: SOAP_OK

SOAP_FMAC1 int SOAP_FMAC2 soap_wsrm_create	(	struct soap *	soap,
		const char *	to,
		const char *	replyto,
		LONG64	expires,
		const char *	wsa_id,
		soap_wsrm_sequence_handle *	seq
	)

Creates a new sequence. Sequences are usually created by the sender (client) and confirmed by the receiver (server). The 'to' server address must be used for all messages of the sequence to be sent to the WS-RM destination server. Optionally the 'replyto' address can be given of the WS-RM source to reply to. A sequence ID is generated by the server upon success.

Parameters

	soap	context
[in]	to	endpoint address of the WS-RM destination server (required)
[in]	replyto	endpoint address of the WS-RM source to reply/ack to (optional)
[in]	expires	max sequence duration (its lifetime) in ms (use 0 to offer infinite, subject to SOAP_WSRM_MAX_SEC_TO_EXPIRE or server policy)
[in]	wsa_id	WS-Addressing message ID (optional, use NULL when omitted)
[out]	seq	sequence handle is set

Returns: SOAP_OK or error code

SOAP_FMAC1 int SOAP_FMAC2 soap_wsrm_create_offer	(	struct soap *	soap,
		const char *	to,
		const char *	replyto,
		const char *	id,
		LONG64	expires,
		enum wsrm__IncompleteSequenceBehaviorType	behavior,
		const char *	wsa_id,
		soap_wsrm_sequence_handle *	seq
	)

Creates a new sequence by offering suggested WS-RM parameters to the WS-RM destination. Sequences are usually created by the sender (client) and confirmed by the receiver (server). The 'to' server address must be used for all messages of the sequence to be sent to the WS-RM destination server. Optionally the 'replyto' address can be given of the WS-RM source to reply to. A sequence ID is generated by the server upon success.

Parameters

	soap	context
[in]	to	endpoint address of the WS-RM destination server (required)
[in]	replyto	endpoint address of the WS-RM source to reply/ack to (optional)
[in]	id	offered WS-RM sequence identifier (optional, generate with NULL)
[in]	expires	max sequence duration (its lifetime) in ms (use 0 for infinite, subject to SOAP_WSRM_MAX_SEC_TO_EXPIRE or server policy)
[in]	behavior	offered DiscardEntireSequence, DiscardFollowingFirstGap, or NoDiscard, which specifies the WS-RM destination's action when a sequence is closed/terminated when it is incomplete, and notifies the source when failed.
[in]	wsa_id	WS-Addressing message ID (optional, use NULL when omitted)
[out]	seq	sequence handle is set or NULL when response is asynchronously send and the sequence is initialized upon receipt of the create response.

Returns: SOAP_OK or error code

SOAP_FMAC1 int SOAP_FMAC2 soap_wsrm_create_offer_acksto	(	struct soap *	soap,
		const char *	to,
		const char *	replyto,
		const char *	acksto,
		const char *	id,
		LONG64	expires,
		enum wsrm__IncompleteSequenceBehaviorType	behavior,
		const char *	wsa_id,
		soap_wsrm_sequence_handle *	seq
	)

Creates a new sequence by offering suggested WS-RM parameters to the WS-RM destination. Sequences are usually created by the sender (client) and confirmed by the receiver (server). The 'to' server address must be used for all messages of the sequence to be sent to the WS-RM destination server. Optionally the 'replyto' address can be given of the WS-RM source to reply to and an 'acksto' address can be given for acknowledgement messages to be sent to (normally to the reply to). A sequence ID is generated by the server upon success.

Parameters

	soap	context
[in]	to	endpoint address of the WS-RM destination server (required)
[in]	replyto	endpoint address of the WS-RM source (optional)
[in]	acksto	endpoint address for WS-RM acknowledgements (optional) (optional, use NULL when acks are piggy-backed on response messages to the source)
[in]	id	offered WS-RM sequence identifier (optional, generate when NULL)
[in]	expires	max sequence duration (its lifetime) in ms (use 0 for infinite, subject to SOAP_WSRM_MAX_SEC_TO_EXPIRE or server policy)
[in]	behavior	offered DiscardEntireSequence, DiscardFollowingFirstGap, or NoDiscard, which specifies the WS-RM destination's action when a sequence is closed/terminated when it is incomplete, and notifies the source when failed.
[in]	wsa_id	WS-Addressing message ID (optional, use NULL when omitted)
[out]	seq	sequence handle is set or NULL when response is asynchronously send and the sequence is initialized upon receipt of the create response.

Returns: SOAP_OK or error code

static void soap_wsrm_delete	(	struct soap *	soap,
		struct soap_plugin *	p
	)

static

Deletes plugin data.

Parameters

	soap	context
[in,out]	p	plugin

Returns: SOAP_OK

static int soap_wsrm_disconnect ( struct soap * soap )

static

Internal callback function to override fdisconnect(). Turns caching off, sets the cached message to NACK, and resets the server-side handle, so sequence can be deallocated later.

Parameters

soap context

Returns: SOAP_OK or error code

SOAP_FMAC1 void SOAP_FMAC2 soap_wsrm_dump	(	struct soap *	soap,
		FILE *	fd
	)

Dumps the current sequences and details of the wsrm plugin for diagnotics purposes.

Parameters

	soap	context
[in]	fd	file descriptor to send text to

SOAP_FMAC1 int SOAP_FMAC2 soap_wsrm_error	(	struct soap *	soap,
		struct soap_wsrm_sequence *	seq,
		enum wsrm__FaultCodes	fault
	)

Sets SOAP Fault (sub)code for server WS-RM fault response. Terminates the sequence.

Parameters

	soap	context
[in]	seq	pointer to sequence to terminate or NULL
[in]	fault	is one of enum wsrm__FaultCodes enumeration values

Returns: SOAP_FAULT

SOAP_FMAC1 int SOAP_FMAC2 soap_wsrm_fault_subcode	(	struct soap *	soap,
		int	flag,
		const char *	faultsubcode,
		const char *	faultstring,
		const char *	faultdetail
	)

Sets sender/receiver SOAP Fault (sub)code for server faults (can be user defined faults). When called before soap_wsrm_check() in the server operation, terminates the current sequence. Otherwise, the sequence is not terminated. In either case the fault is returned to sender (client) or to the FaultTo server when the WS-Addressing FaultTo header was set by the sender.

Parameters

	soap	context
[in]	flag	0=receiver, 1=sender
[in]	faultsubcode	sub code string
[in]	faultstring	fault string
[in]	faultdetail	detail string

Returns: SOAP_FAULT

static int soap_wsrm_init	(	struct soap *	soap,
		struct soap_wsrm_data *	data,
		void *	arg
	)

static

Initializes plugin data.

Parameters

	soap	context
[in,out]	data	plugin data
[in]	arg	optional argument passed from soap_register_plugin_arg

Returns: SOAP_OK

SOAP_FMAC1 ULONG64 SOAP_FMAC2 soap_wsrm_lastnum ( const soap_wsrm_sequence_handle seq )

Returns the last message number upon sequence close or 0.

Parameters

seq	sequence handle set by soap_wsrm_create() or soap_wsrm_create_offer()

Returns: last message number or 0 when more messages should be received

static int soap_wsrm_msg_append	(	struct soap *	soap,
		struct soap_wsrm_data *	data,
		const char *	buf,
		size_t	len
	)

static

Internal function used by soap_wsrm_send() to append message data to the current message being transmitted in the current sequence.

Parameters

	soap	context
	data	plugin
[in]	buf	message data
[in]	len	message data length

Returns: SOAP_OK or error code

static void soap_wsrm_msg_free	(	struct soap *	soap,
		struct soap_wsrm_message *	p
	)

static

Internal function to deallocate all cached message content from a sequence state.

Parameters

soap	context
p	pointer to message (in a sequence state)

static struct soap_wsrm_message * soap_wsrm_msg_new	(	struct soap *	soap,
		struct soap_wsrm_sequence *	seq,
		ULONG64	num
	)

static

Internal function to allocate a new message in a sequence, updates message count seq->num.

Parameters

soap	context
seq	sequence pointer
num	message num (produces error when zero)

Returns: pointer to message struct or NULL when error

SOAP_FMAC1 ULONG64 SOAP_FMAC2 soap_wsrm_msgs ( const soap_wsrm_sequence_handle seq )

Returns the number of complete messages received, or 0 when there is a gap.

Parameters

[in] seq pointer to sequence

Returns: number of messages received or 0

SOAP_FMAC1 ULONG64 SOAP_FMAC2 soap_wsrm_nack ( const soap_wsrm_sequence_handle seq )

Returns the number of non-acknowledged messages sent.

Parameters

seq	sequence handle set by soap_wsrm_create() or soap_wsrm_create_offer()

Returns: number of non-acknowledged messages sent

SOAP_FMAC1 int SOAP_FMAC2 soap_wsrm_non_acknowledgement	(	struct soap *	soap,
		soap_wsrm_sequence_handle	seq,
		ULONG64	nack
	)

Sends nack non-acknowledgement for a message.

Parameters

soap	context
seq	sequence handle set by soap_wsrm_create or soap_wsrm_create_offer
nack	num of message to nack

Returns: SOAP_OK or error code

SOAP_FMAC1 ULONG64 SOAP_FMAC2 soap_wsrm_num ( const soap_wsrm_sequence_handle seq )

Returns the current message number of the sequence.

Parameters

seq	sequence handle set by soap_wsrm_create() or soap_wsrm_create_offer()

Returns: the sequence endpoint address

static void soap_wsrm_num_free	(	struct soap *	soap,
		struct soap_wsrm_sequence *	seq
	)

static

Internal function to deallocate all message number ranges from a sequence state.

Parameters

soap	context
seq	pointer to sequence

static int soap_wsrm_num_insert	(	struct soap *	soap,
		struct soap_wsrm_sequence *	seq,
		ULONG64	num
	)

static

Internal function to insert a message number in the sequence state. Updates the sequence ranges.

Parameters

	soap	context
	seq	pointer to sequence
[in]	num

Returns: SOAP_OK or error code (out of memory)

static int soap_wsrm_num_lookup	(	struct soap *	soap,
		const struct soap_wsrm_sequence *	seq,
		ULONG64	num
	)

static

Internal function to look up a message number in the sequence state.

Parameters

	soap	context
[in]	seq	pointer to sequence
[in]	num	message num to search

Returns: 0 (not found) 1 (found)

static int soap_wsrm_num_size ( const struct soap_wsrm_sequence * seq )

static

Internal function returns the number of message ranges of the successfully received messages in a sequence state.

Parameters

seq	pointer to sequence

Returns: number of message ranges

static int soap_wsrm_preparefinalrecv ( struct soap * soap )

static

Internal callback function to override fpreparefinalrecv(). Takes acks returned by response to update the states of the sequences with acknowledgements. Acknowledged messages do not have to be resend and are purged from the sequence states. Also checks if at client-side response message was already received and otherwise records it in the state.

Parameters

soap context

Returns: SOAP_OK or error code

static int soap_wsrm_process_ack	(	struct soap *	soap,
		struct _wsrm__SequenceAcknowledgement *	ack
	)

static

Internal function to purge acknowledged messages as given by wsrm:SequenceAcknowledgement header.

Parameters

	soap	context
[in]	ack	from the WS-RM SequenceAcknowledgement header.

Returns: SOAP_OK or error code

SOAP_FMAC1 int SOAP_FMAC2 soap_wsrm_pulse	(	struct soap *	soap,
		int	timeout
	)

Sends acknowledgements for all open sessions to all peers. Must set send and recv timeouts to prevent blocking.

Parameters

soap	context
timeout	seconds (positive value) or microseconds (negative value)

Returns: SOAP_OK or an error code when one or more peers fault (the last error code is returned)

SOAP_FMAC1 int SOAP_FMAC2 soap_wsrm_receiver_fault	(	struct soap *	soap,
		const char *	faultstring,
		const char *	faultdetail
	)

Sets receiver SOAP Fault for server faults (can be user defined faults). When called before soap_wsrm_check() in the server operation, terminates the current sequence. Otherwise, the sequence is not terminated. In either case the fault is returned to sender (client) or to the FaultTo server when the WS-Addressing FaultTo header was set by the sender.

Parameters

	soap	context
[in]	faultstring	fault string
[in]	faultdetail	detail string

Returns: SOAP_FAULT

SOAP_FMAC1 int SOAP_FMAC2 soap_wsrm_receiver_fault_subcode	(	struct soap *	soap,
		const char *	faultsubcode,
		const char *	faultstring,
		const char *	faultdetail
	)

Sets receiver SOAP Fault (sub)code for server faults (can be user defined faults). When called before soap_wsrm_check() in the server operation, terminates the current sequence. Otherwise, the sequence is not terminated. In either case the fault is returned to sender (client) or to the FaultTo server when the WS-Addressing FaultTo header was set by the sender.

Parameters

	soap	context
[in]	faultsubcode	sub code string
[in]	faultstring	fault string
[in]	faultdetail	detail string

Returns: SOAP_FAULT

SOAP_FMAC1 ULONG64 SOAP_FMAC2 soap_wsrm_recvnum ( const soap_wsrm_sequence_handle seq )

Returns the message number of last message received.

Parameters

seq	sequence handle set by soap_wsrm_create() or soap_wsrm_create_offer()

Returns: message number of last message received

SOAP_FMAC1 int SOAP_FMAC2 soap_wsrm_reply	(	struct soap *	soap,
		const char *	wsa_id,
		const char *	wsa_action
	)

Server-side server operation reply to be performed when the service operation returns. Server operations that support WS-Addressing and WS-RM must call this function to return normally (and/or allow the response message to be relayed as per WS-Addressing).

Parameters

	soap	context
[in]	wsa_id	WS-Addressing message ID (optional)
[in]	wsa_action	mandatory WS-Addressing action of the response

Returns: SOAP_OK or error code (and server operation must return this value)

SOAP_FMAC1 int SOAP_FMAC2 soap_wsrm_reply_num	(	struct soap *	soap,
		int	flag
	)

Prepares reply from service. When flag is set, adds a WS-RM sequence message number to the next message transmitted. No acks are requested. No WS-Addressing message relay.

Parameters

soap	context
flag	true to add a WS-RM sequence message number to the message to be transmitted

Returns: SOAP_OK or error code (and server operation must return this value)

SOAP_FMAC1 int SOAP_FMAC2 soap_wsrm_reply_request_acks	(	struct soap *	soap,
		const char *	wsa_id,
		const char *	wsa_action
	)

Server-side server operation reply to be performed when the service operation returns. Message acks for the current sequence are requested, but only when client made a create sequence offer. Server operations that support WS-Addressing and WS-RM must call this function or call soap_wsrm_reply() to return normally (and/or allow the response message to be relayed as per WS-Addressing).

Parameters

	soap	context
[in]	wsa_id	WS-Addressing message ID (optional)
[in]	wsa_action	mandatory WS-Addressing action of the response

Returns: SOAP_OK or error code (and server operation must return this value)

SOAP_FMAC1 int SOAP_FMAC2 soap_wsrm_request	(	struct soap *	soap,
		soap_wsrm_sequence_handle	seq,
		const char *	wsa_id,
		const char *	wsa_action
	)

Adds a WS-RM sequence message number to the next message transmitted to the WS-RM destination and increments the message counter by one. No acks are requested.

Parameters

	soap	context
	seq	sequence handle set by soap_wsrm_create() or soap_wsrm_create_offer()
[in]	wsa_id	WS-Addressing message ID (optional, use NULL when omitted)
[in]	wsa_action	mandatory WS-Addressing action of the next message sent

Returns: SOAP_OK or error code

SOAP_FMAC1 int SOAP_FMAC2 soap_wsrm_request_acks	(	struct soap *	soap,
		soap_wsrm_sequence_handle	seq,
		const char *	wsa_id,
		const char *	wsa_action
	)

Adds a WS-RM sequence message number to the next message transmitted to the WS-RM destination and increments the message counter by one. Message acks for the current sequence are requested.

Parameters

	soap	context
	seq	sequence handle set by soap_wsrm_create() or soap_wsrm_create_offer()
[in]	wsa_id	WS-Addressing message ID (optional, use NULL when omitted)
[in]	wsa_action	mandatory WS-Addressing action of the next message sent

Returns: SOAP_OK or error code

SOAP_FMAC1 int SOAP_FMAC2 soap_wsrm_request_num	(	struct soap *	soap,
		soap_wsrm_sequence_handle	seq,
		const char *	wsa_id,
		const char *	wsa_action,
		ULONG64	num
	)

Adds a WS-RM sequence message number to the next message transmitted. No acks are requested.

Parameters

	soap	context
	seq	sequence handle set by soap_wsrm_create() or soap_wsrm_create_offer()
[in]	wsa_id	WS-Addressing message ID (optional, use NULL when omitted)
[in]	wsa_action	mandatory WS-Addressing action of the next message sent
[in]	num	WS-RM sequence message number

Returns: SOAP_OK or error code

SOAP_FMAC1 int SOAP_FMAC2 soap_wsrm_resend	(	struct soap *	soap,
		soap_wsrm_sequence_handle	seq,
		ULONG64	lower,
		ULONG64	upper
	)

Resend all unacknowledged messages, i.e. messages that were automatically cached for this sequence. Messages stored in the sequence for retransmission (those that were previously sent but not acknowledged) are resent to the soap_wsrm_to() address (which was set by soap_wsrm_create() or soap_wsrm_create_offer(), or the ReplyTo address). It is recommended to resend messages after the last message in the sequence was transmitted before closing the sequence. To reduce unnecessary resend attempts, it is recommended to use soap_wsrm_request_ack() with the last message to request acks for messages already delivered.

Parameters

	soap	context
	seq	sequence handle set by soap_wsrm_create or soap_wsrm_create_offer
[in]	lower	resend message range lower bound (0 for lowest)
[in]	upper	resend message range upper bound (or 0 for infinite)

Returns: SOAP_OK or error code (can be ignored when resends are retried later)

SOAP_FMAC1 int SOAP_FMAC2 soap_wsrm_resend_only_nacked	(	struct soap *	soap,
		soap_wsrm_sequence_handle	seq,
		ULONG64	lower,
		ULONG64	upper
	)

Resend all explicitly nack'ed messages indicaed by peer. Messages stored in the sequence for retransmission (those that were previously sent but not acknowledged) are resent to the soap_wsrm_to() address (which was set by soap_wsrm_create() or soap_wsrm_create_offer(), or the ReplyTo address).

Parameters

	soap	context
	seq	sequence handle set by soap_wsrm_create or soap_wsrm_create_offer
[in]	lower	resend message range lower bound (0 for lowest)
[in]	upper	resend message range upper bound (or 0 for infinite)

Returns: SOAP_OK or error code (can be ignored when resends are retried later)

static int soap_wsrm_resend_seq	(	struct soap *	soap,
		struct soap_wsrm_sequence *	seq,
		int	all,
		ULONG64	lower,
		ULONG64	upper
	)

static

Internal function to resend unacknowledged messages of a sequence given a range of message numbers. Used by soap_wsrm_resend().

Parameters

	soap	context
	seq	sequence handle set by soap_wsrm_create() or soap_wsrm_create_offer()
[in]	all	1= resend all unacknowledged messages (not just the nacked messages)
[in]	lower	resend message range lower bound (0 for lowest)
[in]	upper	resend message range upper bound (or 0 for infinite)

Returns: SOAP_OK or error code (can be ignored to continue sequence)

static int soap_wsrm_send	(	struct soap *	soap,
		const char *	buf,
		size_t	len
	)

static

Internal callback function to override fsend(). When the wsrm plugin is enabled, saves the message to the current sequence that is created at the client side. Allows unacknowledged messages to be resend with soap_wsrm_resend().

Parameters

	soap	context
[in]	buf	message data
[in]	len	message data length

Returns: SOAP_OK or error code

SOAP_FMAC1 int SOAP_FMAC2 soap_wsrm_sender_fault	(	struct soap *	soap,
		const char *	faultstring,
		const char *	faultdetail
	)

Sets sender SOAP Fault for server faults (can be user defined faults). When called before soap_wsrm_check() in the server operation, terminates the current sequence. Otherwise, the sequence is not terminated. In either case the fault is returned to sender (client) or to the FaultTo server when the WS-Addressing FaultTo header was set by the sender.

Parameters

	soap	context
[in]	faultstring	fault string
[in]	faultdetail	detail string

Returns: SOAP_FAULT

SOAP_FMAC1 int SOAP_FMAC2 soap_wsrm_sender_fault_subcode	(	struct soap *	soap,
		const char *	faultsubcode,
		const char *	faultstring,
		const char *	faultdetail
	)

Sets sender SOAP Fault (sub)code for server faults (can be user defined faults). When called before soap_wsrm_check() in the server operation, terminates the current sequence. Otherwise, the sequence is not terminated. In either case the fault is returned to sender (client) or to the FaultTo server when the WS-Addressing FaultTo header was set by the sender.

Parameters

	soap	context
[in]	faultsubcode	sub code string
[in]	faultstring	fault string
[in]	faultdetail	detail string

Returns: SOAP_FAULT

SOAP_FMAC1 struct soap_wsrm_sequence* SOAP_FMAC2 soap_wsrm_seq ( struct soap * soap )

Assuming a SOAP header is received, gets the sequence associated with the message.

Parameters

soap context

Returns: sequence handle, must be released with soap_wsrm_seq_release when no longer used

int soap_wsrm_seq_created	(	struct soap *	soap,
		struct soap_wsrm_sequence *	seq
	)

Function to check if a sequence is created.

Parameters

soap	context
seq	pointer to sequence

Returns: 0 (not created) or 1 (created)

static void soap_wsrm_seq_delete_ack ( struct soap_wsrm_sequence * seq )

static

Internal function to delete acksid for fast lookup.

Parameters

[in] seq sequence

static void soap_wsrm_seq_delete_data ( struct soap_wsrm_sequence * seq )

static

Internal function to delete seq id from hash table.

Parameters

[in] seq sequence

SOAP_FMAC1 void SOAP_FMAC2 soap_wsrm_seq_free	(	struct soap *	soap,
		soap_wsrm_sequence_handle	seq
	)

Must be called to free the sequence allocated by soap_wsrm_create() or by soap_wsrm_create_offer(). Sequences created by soap_wsrm_create_offer return handles that are not automatically reclaimed by the engine.

Parameters

soap	context
seq	sequence handle set by soap_wsrm_create() or soap_wsrm_create_offer()

static struct soap_wsrm_sequence * soap_wsrm_seq_insert ( struct soap * soap )

static

Internal function to create a new local sequence state.

Parameters

soap context

Returns: sequence or NULL

static void soap_wsrm_seq_insert_ack ( struct soap_wsrm_sequence * seq )

static

Internal function to insert acksid for fast lookup.

Parameters

[in] seq sequence

static void soap_wsrm_seq_insert_data ( struct soap_wsrm_sequence * seq )

static

Internal function to insert seq id in hash table for fast lookup.

Parameters

[in] seq sequence

SOAP_FMAC1 struct soap_wsrm_sequence* SOAP_FMAC2 soap_wsrm_seq_lookup	(	struct soap *	soap,
		const char *	id
	)

Function to look up sequence given its id.

Parameters

	soap	context
[in]	id	identifier string

Returns: sequence handle, must be released with soap_wsrm_seq_release when no longer used

static struct soap_wsrm_sequence * soap_wsrm_seq_lookup_ack ( const char * id )

static

Internal function to look up sequence given its acksid.

Parameters

[in] id identifier string

Returns: sequence or NULL

static struct soap_wsrm_sequence * soap_wsrm_seq_lookup_data ( const char * id )

static

Internal function to look up sequence given its id.

Parameters

[in] id identifier string

Returns: sequence or NULL

SOAP_FMAC1 struct soap_wsrm_sequence* SOAP_FMAC2 soap_wsrm_seq_lookup_id	(	struct soap *	soap,
		const char *	id
	)

Function to look up sequence given its id.

Parameters

	soap	context
[in]	id	identifier string

Returns: sequence handle, must be released with soap_wsrm_seq_release when no longer used

static const char * soap_wsrm_seq_newid ( struct soap * soap )

static

Internal function to generate a new sequence identifier.

Parameters

soap context

Returns: sequence identifier string

void soap_wsrm_seq_release	(	struct soap *	soap,
		struct soap_wsrm_sequence *	seq
	)

Releases handle.

Parameters

soap	context
seq	sequence handle

int soap_wsrm_seq_valid	(	struct soap *	soap,
		struct soap_wsrm_sequence *	seq
	)

Function to check if a sequence is not valid, terminated, or needs to be terminated when expired.

Parameters

soap	context
seq	pointer to sequence

Returns: 0 (invalid) or 1 (valid)

static int soap_wsrm_set_ack	(	struct soap *	soap,
		ULONG64	nack,
		struct soap_wsrm_sequence *	seq,
		struct _wsrm__SequenceAcknowledgement *	ack
	)

static

Internal function called by soap_wsrm_add_acks() to populate the SequenceAcknowledgement header block.

Parameters

	soap	context
[in]	nack	num of message to nack, 0 to pupulate ack with ranges from seq
[in]	seq	pointer to sequence
[out]	ack	pointer to SequenceAcknowledgement to populate

SOAP_FMAC1 int SOAP_FMAC2 soap_wsrm_terminate	(	struct soap *	soap,
		soap_wsrm_sequence_handle	seq,
		const char *	wsa_id
	)

Terminates the sequence. No new messages should be send and no resends should be tried. Usually done after soap_wsrm_close() or any time to terminate the sequence prematurely.

Parameters

	soap	context
	seq	sequence handle set by soap_wsrm_create or soap_wsrm_create_offer
[in]	wsa_id	WS-Addressing message ID (optional)

Returns: SOAP_OK or error code

SOAP_FMAC1 const char* SOAP_FMAC2 soap_wsrm_to ( const soap_wsrm_sequence_handle seq )

Returns the endpoint address of the destination service that serves the sequence. Initially set with soap_wsrm_create or soap_wsrm_create_offer. HTTP 307 Temporary Redirect can change the endpoint during the lifetime of a message sequence. Thus, this function returns the most recent endpoint binding that can be used to send message to the server endpoint.

Parameters

seq	sequence handle set by soap_wsrm_create() or soap_wsrm_create_offer()

Returns: the sequence endpoint address or replyTo address (when provided) or NULL when no destination is given

Variable Documentation

const char soap_wsrm_id[] = SOAP_WSRM_ID

Plugin identification for plugin registry

char soap_wsrm_idname[40] = ""

int soap_wsrm_idnum = 0

struct soap_wsrm_sequence* soap_wsrm_session = NULL

static

Sequence session database

MUTEX_TYPE soap_wsrm_session_lock = MUTEX_INITIALIZER

static

Sequence session database lock

Functions

Variables

Function Documentation

Variable Documentation