gSOAP WS-ReliableMessaging  2.8 Stable
Classes | Macros | Typedefs | Enumerations | Functions | Variables
wsrmapi.h File Reference
#include "wsaapi.h"
#include "threads.h"
Include dependency graph for wsrmapi.h:
This graph shows which files directly or indirectly include this file:

Classes

struct  soap_wsrm_data
 Plugin data. More...
 
struct  soap_wsrm_message
 Linked list of unacknowledged messages stored for retransmission. More...
 
struct  soap_wsrm_content
 Linked list of message content blocks. More...
 
struct  soap_wsrm_range
 
struct  soap_wsrm_sequence
 Linked list of currently active message sequences. More...
 

Macros

#define SOAP_WSRM_ID   "WS-RM-1.2"
 
#define SOAP_WSRM_MAX_RETRIES   100
 
#define SOAP_WSRM_MAX_SEC_TO_EXPIRE   600 /* 600 sec = 10 minutes */
 
#define SOAP_WSRM_TIMEOUT   10
 
#define SOAP_WSRM_NOCHAN   0x7FFFFFFF
 

Typedefs

typedef struct soap_wsrm_sequencesoap_wsrm_sequence_handle
 

Enumerations

enum  soap_wsrm_enable { SOAP_WSRM_OFF, SOAP_WSRM_ON }
 
enum  soap_wsrm_message_state { SOAP_WSRM_NACK, SOAP_WSRM_ACK }
 Message state (nack or ack) More...
 
enum  soap_wsrm_state {
  SOAP_WSRM_NONE, SOAP_WSRM_UNKNOWN, SOAP_WSRM_CREATED, SOAP_WSRM_CLOSED,
  SOAP_WSRM_TERMINATED
}
 wsrm engine state More...
 

Functions

int soap_wsrm (struct soap *soap, struct soap_plugin *plugin, void *arg)
 Plugin registry function, used with soap_register_plugin.
 
int 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.
 
int 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.
 
int 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.
 
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(), 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.
 
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.
 
int 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.
 
int soap_wsrm_acknowledgement (struct soap *soap, soap_wsrm_sequence_handle seq, const char *wsa_id)
 Sends acknowledgements.
 
soap_wsrm_sequence_handle soap_wsrm_seq (struct soap *soap)
 Assuming a SOAP header is received, gets the sequence associated with the message.
 
void soap_wsrm_seq_release (struct soap *soap, soap_wsrm_sequence_handle seq)
 
int soap_wsrm_seq_created (struct soap *soap, soap_wsrm_sequence_handle seq)
 
int soap_wsrm_seq_valid (struct soap *soap, soap_wsrm_sequence_handle seq)
 
soap_wsrm_sequence_handle soap_wsrm_seq_lookup_id (struct soap *soap, const char *id)
 Function to look up sequence given its id.
 
soap_wsrm_sequence_handle soap_wsrm_seq_lookup (struct soap *soap, const char *id)
 Function to look up sequence given its id.
 
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(). Sequences created by soap_wsrm_create_offer return handles that are not automatically reclaimed by the engine.
 
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().
 
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.
 
ULONG64 soap_wsrm_msgs (struct soap *soap, const struct soap_wsrm_sequence *seq)
 Returns the number of complete messages received, or 0 when there is a gap.
 
int 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.
 
int 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.
 
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/or allow the response message to be relayed as per WS-Addressing).
 
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 call soap_wsrm_reply() to return normally (and/or allow the response message to be relayed as per WS-Addressing).
 
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 __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__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.
 
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__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.
 
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 terminate sequence request. Updates the server's local sequence state to terminated.
 
int __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.
 
int __wsrm__SequenceAcknowledgement (struct soap *soap)
 WS-RM SequenceAcknowledgement operation.
 
SOAP_FMAC5 int SOAP_FMAC6 soap_call___wsrm__CreateSequence (struct soap *soap, const char *soap_endpoint, const char *soap_action, struct wsrm__CreateSequenceType *wsrm__CreateSequence, struct wsrm__CreateSequenceResponseType *wsrm__CreateSequenceResponse)
 
SOAP_FMAC5 int SOAP_FMAC6 soap_call___wsrm__CloseSequence (struct soap *soap, const char *soap_endpoint, const char *soap_action, struct wsrm__CloseSequenceType *wsrm__CloseSequence, struct wsrm__CloseSequenceResponseType *wsrm__CloseSequenceResponse)
 
SOAP_FMAC5 int SOAP_FMAC6 soap_call___wsrm__TerminateSequence (struct soap *soap, const char *soap_endpoint, const char *soap_action, struct wsrm__TerminateSequenceType *wsrm__TerminateSequence, struct wsrm__TerminateSequenceResponseType *wsrm__TerminateSequenceResponse)
 
SOAP_FMAC5 int SOAP_FMAC6 soap_send___wsrm__SequenceAcknowledgement (struct soap *soap, const char *soap_endpoint, const char *soap_action)
 
SOAP_FMAC5 int SOAP_FMAC6 soap_recv___wsrm__SequenceAcknowledgement (struct soap *soap, struct __wsrm__SequenceAcknowledgement *)
 
SOAP_FMAC5 int SOAP_FMAC6 soap_send___wsrm__LastMessage (struct soap *soap, const char *soap_endpoint, const char *soap_action)
 

Variables

const char soap_wsrm_id []
 

Macro Definition Documentation

#define SOAP_WSRM_ID   "WS-RM-1.2"

Plugin identification for plugin registry

#define SOAP_WSRM_MAX_RETRIES   100

Max number of retries that soap_wsrm_check_retry can succeed

#define SOAP_WSRM_MAX_SEC_TO_EXPIRE   600 /* 600 sec = 10 minutes */

Max seconds to expire a non-terminated sequence and reclaim its resources

#define SOAP_WSRM_NOCHAN   0x7FFFFFFF

WCF channel instance default value (no channel)

#define SOAP_WSRM_TIMEOUT   10

Seconds to timeout when sending ack messages to independent acksto server

Typedef Documentation

Enumeration Type Documentation

Enumerator
SOAP_WSRM_OFF 
SOAP_WSRM_ON 

Message state (nack or ack)

Enumerator
SOAP_WSRM_NACK 
SOAP_WSRM_ACK 

wsrm engine state

Sequence state.

Enumerator
SOAP_WSRM_NONE 
SOAP_WSRM_UNKNOWN 
SOAP_WSRM_CREATED 
SOAP_WSRM_CLOSED 
SOAP_WSRM_TERMINATED 

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
soapcontext
[in]reqwsrm__CloseSequence request message
[out]reswsrm__CloseSequenceResponse response message
Returns
SOAP_OK or error code
int __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
soapcontext
[in]reswsrm__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
soapcontext
[in]reqwsrm__CreateSequence request message
[out]reswsrm__CreateSequenceResponse response message
Returns
SOAP_OK or error code
int __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
soapcontext
[in]reswsrm__CreateSequenceResponse response message
Returns
SOAP_OK or error code
int __wsrm__SequenceAcknowledgement ( struct soap *  soap)

WS-RM SequenceAcknowledgement operation.

Parameters
soapcontext
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 terminate sequence request. Updates the server's local sequence state to terminated.

Parameters
soapcontext
[in]reqwsrm__TerminateSequence request message
[out]reswsrm__TerminateSequenceResponse response message
Returns
SOAP_OK or error code
int __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
soapcontext
[in]reswsrm__TerminateSequenceResponse response message
Returns
SOAP_OK or error code
SOAP_FMAC5 int SOAP_FMAC6 soap_call___wsrm__CloseSequence ( struct soap *  soap,
const char *  soap_endpoint,
const char *  soap_action,
struct wsrm__CloseSequenceType wsrm__CloseSequence,
struct wsrm__CloseSequenceResponseType wsrm__CloseSequenceResponse 
)
SOAP_FMAC5 int SOAP_FMAC6 soap_call___wsrm__CreateSequence ( struct soap *  soap,
const char *  soap_endpoint,
const char *  soap_action,
struct wsrm__CreateSequenceType wsrm__CreateSequence,
struct wsrm__CreateSequenceResponseType wsrm__CreateSequenceResponse 
)
SOAP_FMAC5 int SOAP_FMAC6 soap_call___wsrm__TerminateSequence ( struct soap *  soap,
const char *  soap_endpoint,
const char *  soap_action,
struct wsrm__TerminateSequenceType wsrm__TerminateSequence,
struct wsrm__TerminateSequenceResponseType wsrm__TerminateSequenceResponse 
)
SOAP_FMAC5 int SOAP_FMAC6 soap_recv___wsrm__SequenceAcknowledgement ( struct soap *  soap,
struct __wsrm__SequenceAcknowledgement  
)
SOAP_FMAC5 int SOAP_FMAC6 soap_send___wsrm__LastMessage ( struct soap *  soap,
const char *  soap_endpoint,
const char *  soap_action 
)
SOAP_FMAC5 int SOAP_FMAC6 soap_send___wsrm__SequenceAcknowledgement ( struct soap *  soap,
const char *  soap_endpoint,
const char *  soap_action 
)
int soap_wsrm ( struct soap *  soap,
struct soap_plugin *  p,
void *  arg 
)

Plugin registry function, used with soap_register_plugin.

Parameters
soapcontext
[in,out]pplugin created in registry
[in]argoptional argument passed from soap_register_plugin_arg
Returns
SOAP_OK
int soap_wsrm_acknowledgement ( struct soap *  soap,
soap_wsrm_sequence_handle  seq,
const char *  wsa_id 
)

Sends acknowledgements.

Parameters
soapcontext
seqsequence handle set by soap_wsrm_create or soap_wsrm_create_offer
[in]wsa_idWS-Addressing message ID (optional)
Returns
SOAP_OK or error code
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
seqsequence handle set by soap_wsrm_create() or soap_wsrm_create_offer()
Returns
the sequence endpoint address
int 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.

Parameters
soapcontext
Returns
SOAP_OK or SOAP_STOP (duplicate message error, should be returned by the service operation executing the soap_wsrm_check) or an error code (and server operation should also 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
soapcontext
[out]faultcode
[out]infostring 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
soapcontext
seqsequence 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
soapcontext
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
soapcontext
seqsequence handle set by soap_wsrm_create or soap_wsrm_create_offer
[in]wsa_idWS-Addressing message ID (optional)
Returns
SOAP_OK or error code
int 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
soapcontext
[in]toendpoint address of the WS-RM destination server (required)
[in]replytoendpoint address of the WS-RM source to reply/ack to (optional)
[in]expiresmax sequence duration (its lifetime) in ms (use 0 to offer infinite, subject to server policy)
[in]wsa_idWS-Addressing message ID (optional, use NULL when omitted)
[out]seqsequence handle is set
Returns
SOAP_OK or error code
int 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
soapcontext
[in]toendpoint address of the WS-RM destination server (required)
[in]replytoendpoint address of the WS-RM source to reply/ack to (optional)
[in]idoffered WS-RM sequence identifier (optional, generate with NULL)
[in]expiresmax sequence duration (its lifetime) in ms (use 0 for infinite, subject to server policy)
[in]behavioroffered 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_idWS-Addressing message ID (optional, use NULL when omitted)
[out]seqsequence 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
int 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
soapcontext
[in]toendpoint address of the WS-RM destination server (required)
[in]replytoendpoint address of the WS-RM source (optional)
[in]ackstoendpoint address for WS-RM acknowledgements (optional) (optional, use NULL when acks are piggy-backed on response messages to the source)
[in]idoffered WS-RM sequence identifier (optional, generate when NULL)
[in]expiresmax sequence duration (its lifetime) in ms (use 0 for infinite, subject to server policy)
[in]behavioroffered 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_idWS-Addressing message ID (optional, use NULL when omitted)
[out]seqsequence 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
void soap_wsrm_dump ( struct soap *  soap,
FILE *  fd 
)

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

Parameters
soapcontext
[in]fdfile 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
soapcontext
[in]seqpointer to sequence to terminate or NULL
[in]faultis 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
soapcontext
[in]flag0=receiver, 1=sender
[in]faultsubcodesub code string
[in]faultstringfault string
[in]faultdetaildetail string
Returns
SOAP_FAULT
ULONG64 soap_wsrm_msgs ( struct soap *  soap,
const struct soap_wsrm_sequence seq 
)

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

Parameters
soapcontext
[in]seqpointer to sequence
Returns
number of messages received or 0
ULONG64 soap_wsrm_nack ( soap_wsrm_sequence_handle  seq)

Returns the number of non-acknowledged messages sent.

Parameters
seqsequence 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
seqsequence handle set by soap_wsrm_create() or soap_wsrm_create_offer()
Returns
the sequence endpoint address
int 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
soapcontext
timeoutseconds (positive value) or microseconds (negative value)
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
soapcontext
[in]faultstringfault string
[in]faultdetaildetail 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
soapcontext
[in]faultsubcodesub code string
[in]faultstringfault string
[in]faultdetaildetail 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/or allow the response message to be relayed as per WS-Addressing).

Parameters
soapcontext
[in]wsa_idWS-Addressing message ID (optional)
[in]wsa_actionmandatory 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,
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
soapcontext
flagtrue 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)
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 call soap_wsrm_reply() to return normally (and/or allow the response message to be relayed as per WS-Addressing).

Parameters
soapcontext
[in]wsa_idWS-Addressing message ID (optional)
[in]wsa_actionmandatory 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
soapcontext
seqsequence handle set by soap_wsrm_create() or soap_wsrm_create_offer()
[in]wsa_idWS-Addressing message ID (optional, use NULL when omitted)
[in]wsa_actionmandatory 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
soapcontext
seqsequence handle set by soap_wsrm_create() or soap_wsrm_create_offer()
[in]wsa_idWS-Addressing message ID (optional, use NULL when omitted)
[in]wsa_actionmandatory 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
soapcontext
seqsequence handle set by soap_wsrm_create() or soap_wsrm_create_offer()
[in]wsa_idWS-Addressing message ID (optional, use NULL when omitted)
[in]wsa_actionmandatory WS-Addressing action of the next message sent
[in]numWS-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(), 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
soapcontext
seqsequence handle set by soap_wsrm_create or soap_wsrm_create_offer
[in]lowerresend message range lower bound (0 for lowest)
[in]upperresend 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_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
soapcontext
[in]faultstringfault string
[in]faultdetaildetail 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
soapcontext
[in]faultsubcodesub code string
[in]faultstringfault string
[in]faultdetaildetail string
Returns
SOAP_FAULT
struct soap_wsrm_sequence * soap_wsrm_seq ( struct soap *  soap)
read

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

Parameters
soapcontext
Returns
sequence handle, must be released with soap_wsrm_seq_release when no longer used
int soap_wsrm_seq_created ( struct soap *  soap,
soap_wsrm_sequence_handle  seq 
)
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(). Sequences created by soap_wsrm_create_offer return handles that are not automatically reclaimed by the engine.

Parameters
soapcontext
seqsequence handle set by soap_wsrm_create() or soap_wsrm_create_offer()
struct soap_wsrm_sequence * soap_wsrm_seq_lookup ( struct soap *  soap,
const char *  id 
)
read

Function to look up sequence given its id.

Parameters
soapcontext
[in]ididentifier string
Returns
sequence handle, must be released with soap_wsrm_seq_release when no longer used
struct soap_wsrm_sequence * soap_wsrm_seq_lookup_id ( struct soap *  soap,
const char *  id 
)
read

Function to look up sequence given its id.

Parameters
soapcontext
[in]ididentifier string
Returns
sequence handle, must be released with soap_wsrm_seq_release when no longer used
void soap_wsrm_seq_release ( struct soap *  soap,
soap_wsrm_sequence_handle  seq 
)
int soap_wsrm_seq_valid ( struct soap *  soap,
soap_wsrm_sequence_handle  seq 
)
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
soapcontext
seqsequence handle set by soap_wsrm_create or soap_wsrm_create_offer
[in]wsa_idWS-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
seqsequence 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[]

Plugin identification for plugin registry