/Users/engelen/Projects/gsoap/plugin/wsrmapi.c File Reference

#include "wsrmapi.h"

Include dependency graph for wsrmapi.c:

Functions
int	soap_wsrm_init (struct soap *soap, struct soap_wsrm_data *data, void *arg)
	Initializes plugin data.
int	soap_wsrm_copy (struct soap *soap, struct soap_plugin *p, struct soap_plugin *q)
	Copy plugin data.
void	soap_wsrm_delete (struct soap *soap, struct soap_plugin *p)
	Deletes plugin data.
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().
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.
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.
int	soap_wsrm_process_ack (struct soap *soap, struct _wsrm__SequenceAcknowledgement *ack)
	Internal function to purge acknowledged messages as given by wsrm:SequenceAcknowledgement header.
int	soap_wsrm_add_acks (struct soap *soap)
	Internal function to add SequenceAcknowledgement headers for AckRequested. Sends acknowledgements to the AcksTo destination service or back to the source. These sends can take SOAP_WSRM_TIMEOUT seconds time, with at most 10 retries performed.
int	soap_wsrm_set_ack (struct soap *soap, struct soap_wsrm_sequence *seq, struct _wsrm__SequenceAcknowledgement *ack)
	Internal function called by soap_wsrm_add_acks() to populate the SequenceAcknowledgement header block.
int	soap_wsrm_resend_seq (struct soap *soap, struct soap_wsrm_sequence *seq, ULONG64 lower, ULONG64 upper)
	Internal function to resend unacknowledged messages of a sequence given a range of message numbers. Used by soap_wsrm_resend().
const char *	soap_wsrm_seq_newid (struct soap *soap, struct soap_wsrm_data *data)
	Internal function to generate a new sequence identifier.
soap_wsrm_sequence *	soap_wsrm_seq_lookup (const struct soap_wsrm_data *data, const char *id)
	Internal function to look up sequence given its id.
soap_wsrm_sequence *	soap_wsrm_seq_lookup_ack (const struct soap_wsrm_data *data, const char *id)
	Internal function to look up sequence given its acksid.
soap_wsrm_sequence *	soap_wsrm_seq_insert (struct soap *soap, struct soap_wsrm_data *data)
	Internal function to create a new local sequence state.
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 for the current sequence.
int	soap_wsrm_seq_terminated (struct soap *soap, struct soap_wsrm_sequence *seq)
	Internal function to check if a sequence is terminated or needs to be terminated when expired.
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.
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.
int	soap_wsrm_num_size (const struct soap_wsrm_sequence *seq)
	Internal function returns the number of message ranges in a sequence state.
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.
soap_wsrm_message *	soap_wsrm_msg_new (struct soap *soap, struct soap_wsrm_sequence *seq, ULONG64 num)
	Internal function to allocate a new message for a sequence sequence state.
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.
int	soap_wsrm_create (struct soap *soap, const char *to, const char *acksto, 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 server. Optionally the 'acksto' address can be given for acknowledgement messages to be sent to. A sequence ID is generated by the server upon success.
int	soap_wsrm_create_offer (struct soap *soap, const char *to, 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 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 server. Optionally the 'acksto' address can be given for acknowledgement messages to be sent to. server upon success.
int	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.
int	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.
int	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.
int	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.
int	soap_wsrm_resend (struct soap *soap, soap_wsrm_sequence_handle seq, ULONG64 lower, ULONG64 upper)
	Client-side call to resend all non-acknowledged 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(). 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.
int	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.
int	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.
void	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(). Sequence handles are not automatically reclaimed by the engine.
const char *	soap_wsrm_to (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.
const char *	soap_wsrm_acksto (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.
ULONG64	soap_wsrm_num (soap_wsrm_sequence_handle seq)
	Returns the current message number of the sequence.
ULONG64	soap_wsrm_nack (soap_wsrm_sequence_handle seq)
	Returns the number of non-acknowledged messages sent.
int	soap_wsrm_check (struct soap *soap)
	Server-side check for the presence of WS-Addressing and WS-RM header blocks in the SOAP header. 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.
int	soap_wsrm_reply_num (struct soap *soap)
	Adds a WS-RM sequence message number to the next message transmitted. No acks are requested. No WS-Addressing relay.
int	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 allow the response to be relayed).
int	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 soap_wsrm_reply() to return normally (and allow the response to be relayed).
void	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().
int	__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.
int	__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.
int	__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 close sequence request. Updates the server's local sequence state to terminated.
int	__wsrm__SequenceAcknowledgement (struct soap *soap)
	WS-RM SequenceAcknowledgement service operation of the AcksTo destination service for relayed acknowledgements. Invoked by the server. The AcksTo server maintains the messages that are acknowledged by updating its local sequence state information by registering message acknowledgement receipts.
int	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.
int	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.
int	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.
int	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.
int	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.
int	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.
int	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.
void	soap_wsrm_dump (struct soap *soap, FILE *fd)
	Dumps the current sequences and details of the wsrm plugin for diagnotics purposes.
int	soap_wsrm (struct soap *soap, struct soap_plugin *p, void *arg)
	Plugin registry function, used with soap_register_plugin.
Variables
const char	soap_wsrm_id [] = SOAP_WSRM_ID
soap_wsrm_sequence *	soap_wsrm_session = NULL
const char *	soap_wsrm_idname = NULL
unsigned long	soap_wsrm_idnum = 0
MUTEX_TYPE	soap_wsrm_session_lock = MUTEX_INITIALIZER

---

Function Documentation

int __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

int __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

int __wsrm__SequenceAcknowledgement (  struct soap *  soap  )

WS-RM SequenceAcknowledgement service operation of the AcksTo destination service for relayed acknowledgements. Invoked by the server. The AcksTo server maintains the messages that are acknowledged by updating its local sequence state information by registering message acknowledgement receipts. Parameters: soap  context Returns: SOAP_OK or error code

int __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 close 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

int 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

const char* soap_wsrm_acksto (  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

int soap_wsrm_add_acks (  struct soap *  soap  )  [static]

Internal function to add SequenceAcknowledgement headers for AckRequested. Sends acknowledgements to the AcksTo destination service or back to the source. These sends can take SOAP_WSRM_TIMEOUT seconds time, with at most 10 retries performed. Parameters: soap  context Returns: SOAP_OK or error code

int soap_wsrm_check (  struct soap *  soap  )

Server-side check for the presence of WS-Addressing and WS-RM header blocks in the SOAP header. 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 Returns: SOAP_OK or error code (and server operation must return this value)

int 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

int 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

void 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

int 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

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

Copy plugin data. Parameters: soap  context [out]  p  plugin [in]  q  plugin Returns: SOAP_OK

int soap_wsrm_create (  struct soap *  soap, const char *  to, const char *  acksto, 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 server. Optionally the 'acksto' address can be given for acknowledgement messages to be sent 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]  acksto  endpoint address of the WS-RM acknowledgement server (optional, use NULL when acks are piggy-backed on response messages to the source) [in]  expires  max sequence duration (its lifetime) in ms (use 0 for inifinite) [in]  wsa_id  WS-Addressing message ID (optional, use NULL when omitted) [out]  seq  sequence handle is set Returns: SOAP_OK or error code

int soap_wsrm_create_offer (  struct soap *  soap, const char *  to, 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 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 server. Optionally the 'acksto' address can be given for acknowledgement messages to be sent to. server upon success. Parameters: soap  context [in]  to  endpoint address of the WS-RM destination server (required) [in]  acksto  endpoint address of the WS-RM acknowledgement server (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 inifinite) [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 Returns: SOAP_OK or error code

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

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

void 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

int 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

int 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

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

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 for the current sequence. Parameters: soap  context data  plugin [in]  buf  message data [in]  len  message data length Returns: SOAP_OK or error code

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)

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 for a sequence sequence state. Parameters: soap  context seq  sequence pointer num  message num Returns: pointer to msg

ULONG64 soap_wsrm_nack (  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: the sequence endpoint address

ULONG64 soap_wsrm_num (  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

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

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)

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)

int soap_wsrm_num_size (  const struct soap_wsrm_sequence *  seq  )  [static]

Internal function returns the number of message ranges in a sequence state. Parameters: seq  pointer to sequence Returns: number of message ranges

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

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

int 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

int 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

int 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 allow the response to be relayed). 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)

int soap_wsrm_reply_num (  struct soap *  soap  )

Adds a WS-RM sequence message number to the next message transmitted. No acks are requested. No WS-Addressing relay. Parameters: soap  context Returns: SOAP_OK or error code (and server operation must return this value)

int 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 soap_wsrm_reply() to return normally (and allow the response to be relayed). 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)

int 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

int 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

int 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

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

Client-side call to resend all non-acknowledged 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(). 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)

int soap_wsrm_resend_seq (  struct soap *  soap, struct soap_wsrm_sequence *  seq, 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]  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)

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

int 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

int 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

void 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(). Sequence handles are not automatically reclaimed by the engine. Parameters: soap  context seq  sequence handle set by soap_wsrm_create() or soap_wsrm_create_offer()

struct soap_wsrm_sequence * soap_wsrm_seq_insert (  struct soap *  soap, struct soap_wsrm_data *  data )  [static]

Internal function to create a new local sequence state. Parameters: soap  context data  plugin Returns: sequence or NULL

struct soap_wsrm_sequence * soap_wsrm_seq_lookup (  const struct soap_wsrm_data *  data, const char *  id )  [static]

Internal function to look up sequence given its id. Parameters: data  plugin [in]  id  identifier string Returns: sequence or NULL

struct soap_wsrm_sequence * soap_wsrm_seq_lookup_ack (  const struct soap_wsrm_data *  data, const char *  id )  [static]

Internal function to look up sequence given its acksid. Parameters: data  plugin [in]  id  identifier string Returns: sequence or NULL

const char * soap_wsrm_seq_newid (  struct soap *  soap, struct soap_wsrm_data *  data )  [static]

Internal function to generate a new sequence identifier. Parameters: soap  context data  plugin Returns: sequence identifier string

int soap_wsrm_seq_terminated (  struct soap *  soap, struct soap_wsrm_sequence *  seq )  [static]

Internal function to check if a sequence is terminated or needs to be terminated when expired. Parameters: soap  context seq  pointer to sequence Returns: 0 (not terminated) or 1 (terminated)

int soap_wsrm_set_ack (  struct soap *  soap, 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]  seq  pointer to sequence [out]  ack  pointer to SequenceAcknowledgement to populate

int 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

const char* soap_wsrm_to (  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

---

Variable Documentation

const char soap_wsrm_id[] = SOAP_WSRM_ID

Plugin identification for plugin registry

const char* soap_wsrm_idname = NULL

unsigned long 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

---