amarquee.library/QMessageOp           amarquee.library/QMessageOp

   NAME
    QMessageOp - Send a message to one or more other clients.

   SYNOPSIS
    #include 

    LONG QMessageOp(struct QSession * session, char * hosts, void * buffer, ULONG bufferLength)

   FUNCTION
    This function allows you to send a buffer of data to other clients
    on the AMarquee server without permanently storing any information 
    on the server.  This can be more efficient than using subscriptions
    to transmit data, and it allows you to easily specify which clients
    should receive the message, on a per-message basis.

    Your message will be sent to every host that matches the regular 
    expression specified in the "hosts" argument, provided that that
    host has specified that it will accept messages from your client
    (via QSetMessageAccessOp).  The regular expression in "hosts" 
    should be of the form "/foo/bar".
    
    If no other clients received your message (either because no clients 
    matching your specification existed, or because they have not granted
    you message access), you will be receive a QERROR_UNPRIVILEGED 
    QMessage notifying you of this.

    When another client sends your client a QMessageOp, the QMessage you
    receive will have a qm_ID of zero, and the qm_Path field will contain 
    the path of the home node of the message's sender (e.g. "/host/prog").
    
    This function may also be used in direct client-to-client
    connections (as created via QNewSession and QNewHostSession),
    in which case the data in the arguments is received directly by
    the other client.

   NOTE
    By default, all clients have messaging access turned off.  So
    in order to send a message to a client, that client must have
    first allowed it with QSetMessageAccessOp.
    
    Data passed with this function will be streamed, so you do not
    have to worry about synchronization.
    
   INPUTS
    session      - The session to wish to send the message op to.
    hosts        - A regular expression indicating which set of clients
                   you wish to send the message to.  It must be of the
                   form "/foo/bar".  For example:  to send your message
                   to all clients named "Bob", do "/#?/Bob".
    buffer       - A pointer to the first byte of the data buffer you
                   wish to transmit.  If NULL is specified, a one-byte
                   buffer containing the NUL byte will be transmitted.
    bufferLength - The length of the data buffer, in bytes.
    
   RESULTS
    Returns the assigned ID number of the message operation on success,
    or 0 on failure.  Any server-side errors will be sent asynchronously
    as QMessages.

   EXAMPLE
    LONG transID;
    LONG data[10] = {1, 2, 3, 4, 5, 6, 7, 8, 9, 10};    
    
    /* Send a message containing the array data to all programs named
       ExampleProgram. */
    if (transID = QMessageOp(session, "/#?/ExampleProgram", data, sizeof(data)))
       printf("Message op succeeded, was given id #%li\n",transID);
    else 
       printf("Message op failed.  (no memory?)\n");

   AREXX NOTES
    In ARexx, the fourth argument is optional.  If it is not specified,
    then the length of the third argument will be computed automatically
    so that the entire ARexx string is sent.  (that is, it defaults to
    length(data)+1.  Note that if you specify the fourth argument to
    be a value of less than that, it will be stored on the server as
    an unterminated character array!)

   AREXX EXAMPLE
    transID = QMessageOp(session, '/#?/ExampleProgram', 'Hey Everybody!')
    if (transID = 0) then say "Oops, operation failed"
    
   SEE ALSO
    QGo, QSetMessageAccessOp, QSysMessageOp