Main Page | Modules | Class Hierarchy | Class List | File List | Class Members | Related Pages

MqSendS API
[MqS API]

collecting and sending all items of a Msgque packet More...

Functions

MQ_EXTERN void MqSendC (MqSendSP const send, const MQ_STR in)
 append a MQ_STR to the MqSendS
MQ_EXTERN void MqSendV (MqSendSP const send, const char *fmt,...)
 append a vararg string to the MqSendS
MQ_EXTERN void MqSendVL (MqSendSP const send, const char *fmt, va_list ap)
 append a vararg list to the MqSendS
MQ_EXTERN void MqSend2 (MqSendSP const send, const MQ_INT2 in)
 append a MQ_INT2 to the MqSendS
MQ_EXTERN void MqSend4 (MqSendSP const send, const MQ_INT4 in)
 append a MQ_INT4 to the MqSendS
MQ_EXTERN void MqSend8 (MqSendSP const send, const MQ_INT8 in)
 append a MQ_INT8 to the MqSendS
MQ_EXTERN void MqSendF (MqSendSP const send, const MQ_FLT4 in)
 append a MQ_FLT4 to the MqSendS
MQ_EXTERN void MqSendD (MqSendSP const send, const MQ_FLT8 in)
 append a MQ_FLT8 to the MqSendS
MQ_EXTERN void MqSendP (MqSendSP const send, const MQ_PTR in)
 append a MQ_PTR to the MqSendS
MQ_EXTERN void MqSendB (MqSendSP const send, const MQ_BIN in, const MQ_SIZE len)
 append a MQ_BIN with MQ_SIZE to the MqSendS
MQ_EXTERN void MqSendU (MqSendSP send, const MqBufferSP buf)
 append a MqBufferS with to the MqSendS
MQ_EXTERN void MqSendH2 (register MqSendSP const send, const MQ_STR header, const MQ_INT2 value)
 append a MQ_STR MQ_INT2 pair to the MqSendS
MQ_EXTERN void MqSendH4 (register MqSendSP const send, const MQ_STR header, const MQ_INT4 value)
 append a MQ_STR MQ_INT4 pair to the MqSendS
MQ_EXTERN void MqSendH8 (register MqSendSP const send, const MQ_STR header, const MQ_INT8 value)
 append a MQ_STR MQ_INT8 pair to the MqSendS
MQ_EXTERN void MqSendHF (register MqSendSP const send, const MQ_STR header, const MQ_FLT4 value)
 append a MQ_STR MQ_FLT4 pair to the MqSendS
MQ_EXTERN void MqSendHD (register MqSendSP const send, const MQ_STR header, const MQ_FLT8 value)
 append a MQ_STR MQ_FLT8 pair to the MqSendS
MQ_EXTERN void MqSendHP (register MqSendSP const send, const MQ_STR header, const MQ_PTR value)
 append a MQ_STR MQ_PTR pair to the MqSendS
MQ_EXTERN void MqSendHC (register MqSendSP const send, const MQ_STR header, const MQ_STR value)
 append a MQ_STR MQ_STR pair to the MqSendS
MQ_EXTERN void MqSendSTART (MqSendSP const send)
 initialize the MqSendS object and start to create a Msgque package
MQ_EXTERN MqErrorE MqSendEND_RETR (MqSendSP const send, MqTransSP const trans)
 finish and send a return Msgque packet
MQ_EXTERN MqErrorE MqSendEND (MqSendSP const send, const MQ_STR token, MqTransSP const trans)
 finish and send a service Msgque packet without waiting on return
MQ_EXTERN MqErrorE MqSendEND_AND_WAIT (MqSendSP const send, const MQ_STR token, const time_t timeout)
 send a service Msgque packet and waiting on return
MQ_EXTERN MqErrorE MqSendRETURN (MqSendSP const send, const char *const fmt, const char *const proc)
 send a return Msgque packet with data from the current MqErrorS object
MQ_EXTERN MqErrorE MqSendOK (MqSendSP const send)
 send a return Msgque packet with return-code 'O' and "OK" as only item
MQ_EXTERN MqErrorE MqSendPING (MqSendSP const send)
 send a ping service Msgque packet and wait for answer
MQ_EXTERN void MqSend_LST_START (MqSendSP const send)
 start append a list item to the MqSendS
MQ_EXTERN void MqSend_LST_END (MqSendSP const send)
 finish append a list item to the MqSendS
MQ_EXTERN void MqSend_RET_START (MqSendSP const send, const char code, const MQ_INT4 num)
 start append a return item to the MqSendS.
MQ_EXTERN void MqSend_RET_END (MqSendSP const send)
 finish append a return item to the MqSendS
MQ_EXTERN void MqSend_RET_OK (MqSendSP const send)
 append a return item to the MqSendS with return-code 'O'

Detailed Description

collecting and sending all items of a Msgque packet

the management is done by a MqSendS object using a MqIoS object for doing the socket io. every MqS object has only one MqSendS object and every MqSendS object has only one MqS object.

Example:
1: calling a service and wait for an answer 
void MyServiceCall(MqSP  const msgque) {    // the 'Freiburg' object
    MqSendSP  const send = msgque->send; // get the MqSendS object
    MqSendSTART(send);              // init the MqSendS buffer object
    MqSend2(send,int2_value);       // 1. argument: a MQ_INT2 value
    MqSendV(send,"num:%x",num);     // 2. argument: a vararg string value
    MqSendB(send,mypicture,size);   // 3. argument: a binary picture of size length
  // call service "SRV1" and wait maximum 60 seconds for the results
    MqErrorCheck(MqSendEND_AND_WAIT(send,"SRV1",60));
    // ... get the results 
    MqErrorCheck(MqRead?(msgque->read, ???));
    ...
}

2: answer a service call 

static MqErrorE Ot_WAR1(MqSP  const msgque, MQ_PTR data) {
    MqSendSP  const send = msgque->send;        // get the MqSendS object
    MqSendSP  const read = msgque->read;        // get the MqReadS object
    MqSendSTART(send);                      // init the MqSendS buffer object
    MqErrorCheck(MqRead2(read,&myInt2));    // read a MQ_INT2 value
    MqErrorCheck(MqReadC(read,&myStr));     // read a MQ_STR value
    MqErrorCheck(MqReadU(read,&myPic));     // read a MqBufferS object to store the picture data
  // ... do some processing
    MqSend_RET_OK(send);                    // everything OK just set return-status to 'O'
    return MqSendEND_RETR(send,NULL);       // send the package as an answer of a previous service-call
  error:                                    // something is wrong, error back
    return MqSendRETURN(send, MQ_ERROR_PROC_FMT, __func__);
}

Change for 2.0:
the Transaction-API is not needed anymore.
DELETE: MqTransE
DELETE: MqTransGetStatus
DELETE: MqTransGetResult
DELETE: MqTransDelete
DELETE: MqIsTrans
DELETE: MqTransSetResult

Function Documentation

MQ_EXTERN void MqSend_LST_START (  MqSendSP const   send  ) 
 

start append a list item to the MqSendS

Parameters:
send the send member of the MqS object

Example:
create a list item 
MqSend_LST_START(send);     // start a LST item
MqSendX(send,X);            // first LST item
MqSendY(send,Y);            // second LST item
// ... do additional MqSend?
MqSend_LST_END(send);       // finish a LST item

MQ_EXTERN void MqSend_RET_START (  MqSendSP const   send,
const char  code,
const MQ_INT4  num
) 
 

start append a return item to the MqSendS.

for a return message only one return item, as last element, is allowed.

Parameters:
send the send member of the MqS object
code the return-code 'O', 'W' or 'E'
num the return-number

Example:
create a return item 
MqSend_RET_START(send, 'W', 10);    // start a RET (W)arning item list with error-code 10
MqSendX(send,X);                    // first warning message
MqSendY(send,Y);                    // second warning message
// ... do additional MqSend?
MqSend_RET_END(send);               // finish a RET item list

Change for 2.0:
return void and not MqErrorE

MQ_EXTERN MqErrorE MqSendEND (  MqSendSP const   send,
const MQ_STR  token,
MqTransSP const   trans
) 
 

finish and send a service Msgque packet without waiting on return

this procedure is used to call a remote service or answer a service-call.

Parameters:
send the send member of the MqS object
token the 4 byte transaction token used to identify the service
trans transaction pointer, only used for the second case

MQ_EXTERN MqErrorE MqSendEND_AND_WAIT (  MqSendSP const   send,
const MQ_STR  token,
const time_t  timeout
) 
 

send a service Msgque packet and waiting on return

this procedure is used to call a remote service and wait for an answer.

Parameters:
send the send member of the MqS object
token the 4 byte transaction token used to identify the service
timeout the maximum time in seconds to wait for an answer
Change for 2.0:
no need to return the transPtr (e.g. transaction-object) anymore.

MQ_EXTERN MqErrorE MqSendOK (  MqSendSP const   send  ) 
 

send a return Msgque packet with return-code 'O' and "OK" as only item

utility procedure to simplify the send task for return handles.

Example:
the MqSendOK procedure 
MqErrorE
MqSendOK (register MqSendS * const send)
{
  MqSendSTART (send);
  MqSendC (send, "OK");
  MqSend_RET_OK (send);
  MqErrorCheck (MqSendEND_RETR (send, NULL));
  return MQ_OK;
error:
  return MqErrorSAppendV (MQ_ERROR_S, MQ_ERROR_PROC_FMT, __func__);
}

MQ_EXTERN MqErrorE MqSendPING (  MqSendSP const   send  ) 
 

send a ping service Msgque packet and wait for answer

utility procedure to check the remote context for usability. by default, the parent-server-context periodic checking for client usability. this procedure is public to give the client programmer the chance to check the server for usability too.

Returns:
a TIMEOUT error if the remote context is not available.

MQ_EXTERN MqErrorE MqSendRETURN (  MqSendSP const   send,
const char *const   fmt,
const char *const   proc
) 
 

send a return Msgque packet with data from the current MqErrorS object

utility procedure to simplify the send task for service handles.

Example:
the MqSendRETURN procedure 
MqErrorE
MqSendRETURN (register MqSendS * const send, const char *const fmt,
              const char *const proc)
{
  register MqErrorSP error = send->msgque->error;
  MqSendSTART (send);
  switch (MqErrorGetStatus (error))
    {
    case MQ_OK:
      MqSend_RET_OK (send);
      break;
    case MQ_ERROR:
      if (fmt)
        MqErrorSAppendV (error, fmt, proc);
      MqSend_RET_START (send, 'E', MqErrorGetNum (error));
      MqSendU (send, MqErrorGetText (error));
      MqSend_RET_END (send);
      break;
    case MQ_WARNING:
      if (fmt)
        MqErrorSAppendV (error, fmt, proc);
      MqSend_RET_START (send, 'W', MqErrorGetNum (error));
      MqSendU (send, MqErrorGetText (error));
      MqSend_RET_END (send);
      break;
    case MQ_CONTINUE:
      MqPanicV (error, __func__, -1,
                "expect status ERROR or WARNING but got %s",
                MqLogStatus (MqErrorGetStatus (error)));
    }
  MqErrorCheck (MqSendEND_RETR (send, NULL));
  return MQ_OK;
error:
  return MqErrorSAppendV (MQ_ERROR_S, MQ_ERROR_PROC_FMT, __func__);
}

Generated on Tue Nov 23 16:13:06 2004 for libFreiburg by  doxygen 1.3.8-20040928