{"size": 4764, "ext": "scrbl", "max_stars_repo_path": "doc/utils/net/amqp.scrbl", "max_stars_repo_name": "christoff-buerger/sagittarius-scheme", "max_stars_repo_stars_event_min_datetime": "2015-11-07T07:13:35.000Z", "max_stars_repo_stars_event_max_datetime": "2022-02-15T03:35:14.000Z", "max_issues_repo_path": "doc/utils/net/amqp.scrbl", "max_issues_repo_name": "christoff-buerger/sagittarius-scheme", "max_issues_repo_issues_event_min_datetime": "2016-04-28T21:59:59.000Z", "max_issues_repo_issues_event_max_datetime": "2021-07-01T08:42:21.000Z", "max_forks_repo_path": "doc/utils/net/amqp.scrbl", "max_forks_repo_name": "christoff-buerger/sagittarius-scheme", "max_forks_repo_forks_event_min_datetime": "2016-12-28T12:41:23.000Z", "max_forks_repo_forks_event_max_datetime": "2020-02-26T20:52:02.000Z"}
{"max_stars_count": 39, "max_issues_count": 3, "max_forks_count": 4, "avg_line_length": 35.2888888889, "max_line_length": 80, "alphanum_fraction": 0.7285894207}
@; -*- coding: utf-8 -*-

@subsection[:tag "net.amqp"]{(net mq amqp) - AMQP library}

@define[Library]{@name{(net mq amqp)}}
@desc{Providing APIs for @hyperlink[:href "http://www.amqp.org"]{AMQP},
Advanced Message Queuing Protocol.

Currently, the library lacks security layer such as TLS and SAML, and
transaction support.
}

@subsubsection{Example}

Following examples describes how to send and receive messages from
remote queues.

@codeblock{
(import (rnrs) (net mq amqp api))

;; Sends text message to SAMPLE.QUEUE on localhost:5672
(call-with-amqp-connection "localhost" "5672"
  (lambda (conn)
    (call-with-amqp-session conn
      (lambda (session)
        (let ((sender (create-amqp-sender session "SAMPLE.QUEUE"))
              (message (create-amqp-text-message "Hello AMQP!!")))
          (send-amqp-message sender message)
          (destroy-amqp-sender sender))))))

;; Receives text message from SAMPLE.QUEUE on localhost:5672
(call-with-amqp-connection "localhost" "5672"
  (lambda (conn)
    (call-with-amqp-session conn
      (lambda (session)
        (let* ((receiver (create-amqp-receiver session "SAMPLE.QUEUE"))
               (message (receive-amqp-message receiver)
          (destroy-amqp-sender receiver)
          message)))))))
}

@subsubsection{High level APIs}

@define[Function]{@name{amqp-connection?} @args{obj}}
@desc{Returns #t if given @var{obj} is AMQP connection. Otherwise #f.}

@define[Function]{@name{open-amqp-connection} @args{host port}}
@desc{Creates an AMQP connection object.}

@define[Function]{@name{close-amqp-connection!} @args{connection}}
@desc{Closes given AMQP connection.}

@define[Function]{@name{call-with-amqp-connection} @args{host port proc}}
@desc{Creates an AMQP connection and pass it to @var{proc}. Then returns
the result of @var{proc}.

The created connection will be closed both @var{proc} returns or raises
an error. Thus Invoking captured continuation inside of @var{proc} would not
work.
}

@define[Function]{@name{amqp-session?} @args{obj}}
@desc{Returns #t if given @var{obj} is AMQP session. Otherwise #f.}

@define[Function]{@name{begin-amqp-session!} @args{connection}}
@desc{Starts AMQP session on the given @var{connection}}

@define[Function]{@name{end-amqp-session!} @args{session}}
@desc{Ends given AMQP session.}

@define[Function]{@name{call-with-amqp-connection} @args{connection proc}}
@desc{Starts an AMQP session and pass it to @var{proc}. Then returns
the result of @var{proc}.

The stated session will be ended both @var{proc} returns or raises
an error. Thus Invoking captured continuation inside of @var{proc} would not
work.
}

@define[Function]{@name{amqp-sender?} @args{obj}}
@define[Function]{@name{amqp-receiver?} @args{obj}}
@desc{Returns #t if given @var{obj} is AMQP sender and receiver, respectively.
Otherwise #f.}

@define[Function]{@name{create-amqp-sender} @args{session source-queue}}
@define[Function]{@name{create-amqp-receiver} @args{session target-queue}}
@desc{Creates an AMQP sender or receiver, respectively.

@var{source-queue} and @var{target-queue} must be strings and indicating
queue names on the remote server.
}

@define[Function]{@name{destroy-amqp-sender} @args{sender}}
@define[Function]{@name{destroy-amqp-receiver} @args{receiver}}
@desc{Destory given @var{sender} and @var{receiver}, respectively.}

@define[Function]{@name{send-amqp-message} @args{sender message}}
@desc{Sends @var{message} to @var{sender}'s queue.

@var{message} must be am AMQP message object.
}

@define[Function]{@name{receive-amqp-message} @args{receiver :key (timeout #f)}}
@desc{Receives an AMQP message from @var{receiver}'s queue.

Keyword argument @var{timeout} must be #f or integer. If this is specified
then the procedure waits only specified milliseconds.
}

@define[Function]{@name{amqp-message?} @args{obj}}
@desc{Returns #t if given @var{obj} is AMQP message. Otherwise #f.}

@define[Function]{@name{create-amqp-text-message text}}
@define[Function]{@name{create-amqp-binary-message data}}
@define[Function]{@name{create-amqp-mime-message content-type data}}
@desc{Creates an AMQP text message, binary message and data message,
respectively.

@var{text} must be a string. @var{data} must be a bytevector. 
@var{content-type} must be a string.
}

@; TBD accessors

@; TBD low level APIs
@; (net mq amqp types)
@; (net mq amqp transport)
@; (net mq amqp messaging)
@; I think AMQP can be extensible that's why it has 4 layer of specifications.
@; Basically, types and transport are *not* MQ dependent protocol thus
@; it is possible to construct a protocol other than MQ on this transport
@; layer. To make this happen we need to describe this low level APIs
@; especially send-transfer and disposition thing.
@; but for now there is no such thing needed
