Changeset 876f5561 in mainline for uspace/lib/hound/src/protocol.c


Ignore:
Timestamp:
2013-04-10T23:06:52Z (11 years ago)
Author:
Jan Vesely <jano.vesely@…>
Branches:
lfn, master, serial, ticket/834-toolchain-update, topic/msim-upgrade, topic/simplify-dev-export
Children:
f0a647c
Parents:
eb0ef51
Message:

libhound: doxygen

File:
1 edited

Legend:

Unmodified
Added
Removed

  • uspace/lib/hound/src/protocol.c

    reb0ef51 r876f5561  
    4848
    4949enum ipc_methods {
     50        /** Create new context representation on the server side */
    5051        IPC_M_HOUND_CONTEXT_REGISTER = IPC_FIRST_USER_METHOD,
     52        /** Release existing context representation on the server side */
    5153        IPC_M_HOUND_CONTEXT_UNREGISTER,
     54        /** Request list of objects */
    5255        IPC_M_HOUND_GET_LIST,
     56        /** Create new connection */
    5357        IPC_M_HOUND_CONNECT,
     58        /** Destroy connection */
    5459        IPC_M_HOUND_DISCONNECT,
     60        /** Switch IPC pipe to stream mode */
    5561        IPC_M_HOUND_STREAM_ENTER,
     62        /** Switch IPC pipe back to general mode */
    5663        IPC_M_HOUND_STREAM_EXIT,
     64        /** Wait until there is no data in the stream */
    5765        IPC_M_HOUND_STREAM_DRAIN,
    5866};
    5967
     68
     69/** PCM format conversion helper structure */
    6070typedef union {
    6171        struct {
    … …  
    7282 ****/
    7383
     84/** Well defined service name */
    7485const char *HOUND_SERVICE = "audio/hound";
    7586
     87/**
     88 * Start a new audio session.
     89 * @param service Named service typically 'HOUND_SERVICE' constant.
     90 * @return Valid session on success, NULL on failure.
     91 */
    7692hound_sess_t *hound_service_connect(const char *service)
    7793{
    … …  
    84100}
    85101
     102/**
     103 * End an existing audio session.
     104 * @param sess The session.
     105 */
    86106void hound_service_disconnect(hound_sess_t *sess)
    87107{
    … …  
    90110}
    91111
     112/**
     113 * Register a named application context to the audio server.
     114 * @param sess Valid audio session.
     115 * @param name Valid string identifier
     116 * @param record True if the application context wishes to receive data.
     117 * @return Valid ID on success, Error code on failure.
     118 */
    92119hound_context_id_t hound_service_register_context(hound_sess_t *sess,
    93120    const char *name, bool record)
    … …  
    113140}
    114141
     142/**
     143 * Remove application context from the server's list.
     144 * @param sess Valid audio session.
     145 * @param id Valid context id.
     146 * @return Error code.
     147 */
    115148int hound_service_unregister_context(hound_sess_t *sess, hound_context_id_t id)
    116149{
    … …  
    123156}
    124157
     158/**
     159 * Retrieve a list of server side actors.
     160 * @param[in] sess Valid audio session.
     161 * @param[out] ids list of string identifiers.
     162 * @param[out] count Number of elements int the @p ids list.
     163 * @param[in] flags list requirements.
     164 * @param[in] connection name of target actor. Used only if the list should
     165 *            contain connected actors.
     166 * @retval Error code.
     167 */
    125168int hound_service_get_list(hound_sess_t *sess, const char ***ids, size_t *count,
    126169    int flags, const char *connection)
    … …  
    190233}
    191234
     235/**
     236 * Create a new connection between a source and a sink.
     237 * @param sess Valid audio session.
     238 * @param source Source name, valid string.
     239 * @param sink Sink name, valid string.
     240 * @return Error code.
     241 */
    192242int hound_service_connect_source_sink(hound_sess_t *sess, const char *source,
    193243    const char *sink)
    … …  
    212262}
    213263
     264/**
     265 * Destroy an existing connection between a source and a sink.
     266 * @param sess Valid audio session.
     267 * @param source Source name, valid string.
     268 * @param sink Sink name, valid string.
     269 * @return Error code.
     270 */
    214271int hound_service_disconnect_source_sink(hound_sess_t *sess, const char *source,
    215272    const char *sink)
    … …  
    231288}
    232289
     290/**
     291 * Switch IPC exchange to a STREAM mode.
     292 * @param exch IPC exchange.
     293 * @param id context id this stream should be associated with
     294 * @param flags set stream properties
     295 * @param format format of the new stream.
     296 * @param bsize size of the server side buffer.
     297 * @return Error code.
     298 */
    233299int hound_service_stream_enter(async_exch_t *exch, hound_context_id_t id,
    234300    int flags, pcm_format_t format, size_t bsize)
    … …  
    243309}
    244310
     311/**
     312 * Destroy existing stream and return IPC exchange to general mode.
     313 * @param exch IPC exchange.
     314 * @return Error code.
     315 */
    245316int hound_service_stream_exit(async_exch_t *exch)
    246317{
    … …  
    248319}
    249320
     321/**
     322 * Wait until the server side buffer is empty.
     323 * @param exch IPC exchange.
     324 * @return Error code.
     325 */
    250326int hound_service_stream_drain(async_exch_t *exch)
    251327{
    … …  
    253329}
    254330
     331/**
     332 * Write audio data to a stream.
     333 * @param exch IPC exchange in STREAM MODE.
     334 * @param data Audio data buffer.
     335 * @size size of the buffer
     336 * @return Error code.
     337 */
    255338int hound_service_stream_write(async_exch_t *exch, const void *data, size_t size)
    256339{
    … …  
    258341}
    259342
     343/**
     344 * Read data from a stream.
     345 * @param exch IPC exchange in STREAM MODE.
     346 * @param data Audio data buffer.
     347 * @size size of the buffer
     348 * @return Error code.
     349 */
    260350int hound_service_stream_read(async_exch_t *exch, void *data, size_t size)
    261351{
    … …  
    271361static const hound_server_iface_t *server_iface;
    272362
     363/**
     364 * Set hound server interface implementation.
     365 * @param iface Initialized Hound server interface.
     366 */
    273367void hound_service_set_server_iface(const hound_server_iface_t *iface)
    274368{
    … …  
    276370}
    277371
     372/**
     373 * Server side implementation of the hound protocol. IPC connection handler.
     374 * @param iid initial call id
     375 * @param icall pointer to initial call structure.
     376 * @param arg (unused)
     377 */
    278378void hound_connection_handler(ipc_callid_t iid, ipc_call_t *icall, void *arg)
    279379{
    … …  
    291391                switch (IPC_GET_IMETHOD(call)) {
    292392                case IPC_M_HOUND_CONTEXT_REGISTER: {
     393                        /* check interface functions */
    293394                        if (!server_iface || !server_iface->add_context) {
    294395                                async_answer_0(callid, ENOTSUP);
    … …  
    297398                        bool record = IPC_GET_ARG1(call);
    298399                        void *name;
     400
     401                        /* Get context name */
    299402                        int ret =
    300403                            async_data_write_accept(&name, true, 0, 0, 0, 0);
    … …  
    306409                        ret = server_iface->add_context(server_iface->server,
    307410                            &id, name, record);
     411                        /** new context should create a copy */
     412                        free(name);
    308413                        if (ret != EOK) {
    309                                 free(name);
    310414                                async_answer_0(callid, ret);
    311415                        } else {
    … …  
    315419                }
    316420                case IPC_M_HOUND_CONTEXT_UNREGISTER: {
     421                        /* check interface functions */
    317422                        if (!server_iface || !server_iface->rem_context) {
    318423                                async_answer_0(callid, ENOTSUP);
    319424                                break;
    320425                        }
     426
     427                        /* get id, 1st param */
    321428                        hound_context_id_t id = IPC_GET_ARG1(call);
    322429                        const int ret =
    … …  
    326433                }
    327434                case IPC_M_HOUND_GET_LIST: {
     435                        /* check interface functions */
    328436                        if (!server_iface || !server_iface->get_list) {
    329437                                async_answer_0(callid, ENOTSUP);
    330438                                break;
    331439                        }
     440
    332441                        const char **list = NULL;
    333442                        const int flags = IPC_GET_ARG1(call);
    … …  
    336445                        char *conn_name = NULL;
    337446                        int ret = EOK;
     447
     448                        /* get connected actor name if provided */
    338449                        if (conn)
    339450                                ret = async_data_write_accept(
    … …  
    345456                                    conn_name, flags);
    346457                        free(conn_name);
     458
     459                        /* Alloc string sizes array */
    347460                        size_t *sizes = NULL;
    348461                        if (count)
    … …  
    383496                }
    384497                case IPC_M_HOUND_CONNECT: {
     498                        /* check interface functions */
    385499                        if (!server_iface || !server_iface->connect) {
    386500                                async_answer_0(callid, ENOTSUP);
    387501                                break;
    388502                        }
     503
    389504                        void *source = NULL;
    390505                        void *sink = NULL;
     506
     507                        /* read source name */
    391508                        int ret =
    392509                            async_data_write_accept(&source, true, 0, 0, 0, 0);
     510                        /* read sink name */
     511                        if (ret == EOK)
     512                                ret = async_data_write_accept(&sink,
     513                                    true, 0, 0, 0, 0);
     514
     515                        if (ret == EOK)
     516                                ret = server_iface->connect(
     517                                    server_iface->server, source, sink);
     518                        free(source);
     519                        free(sink);
     520                        async_answer_0(callid, ret);
     521                        break;
     522                }
     523                case IPC_M_HOUND_DISCONNECT: {
     524                        /* check interface functions */
     525                        if (!server_iface || !server_iface->disconnect) {
     526                                async_answer_0(callid, ENOTSUP);
     527                                break;
     528                        }
     529
     530                        void *source = NULL;
     531                        void *sink = NULL;
     532
     533                        /* read source name */
     534                        int ret =
     535                            async_data_write_accept(&source, true, 0, 0, 0, 0);
     536                        /*read sink name */
    393537                        if (ret == EOK)
    394538                                ret = async_data_write_accept(&sink,
    … …  
    402546                        break;
    403547                }
    404                 case IPC_M_HOUND_DISCONNECT: {
    405                         if (!server_iface || !server_iface->disconnect) {
    406                                 async_answer_0(callid, ENOTSUP);
    407                                 break;
    408                         }
    409                         void *source = NULL;
    410                         void *sink = NULL;
    411                         int ret =
    412                             async_data_write_accept(&source, true, 0, 0, 0, 0);
    413                         if (ret == EOK)
    414                                 ret = async_data_write_accept(&sink,
    415                                     true, 0, 0, 0, 0);
    416                         if (ret == EOK)
    417                                 ret = server_iface->connect(
    418                                     server_iface->server, source, sink);
    419                         free(source);
    420                         free(sink);
    421                         async_answer_0(callid, ret);
    422                         break;
    423                 }
    424548                case IPC_M_HOUND_STREAM_ENTER: {
     549                        /* check interface functions */
    425550                        if (!server_iface || !server_iface->is_record_context
    426551                            || !server_iface->add_stream
    … …  
    430555                        }
    431556
     557                        /* get parameters */
    432558                        hound_context_id_t id = IPC_GET_ARG1(call);
    433559                        const int flags = IPC_GET_ARG2(call);
    … …  
    439565                        };
    440566                        size_t bsize = IPC_GET_ARG4(call);
     567
    441568                        void *stream;
    442569                        int ret = server_iface->add_stream(server_iface->server,
    … …  
    451578                                if(server_iface->stream_data_read) {
    452579                                        async_answer_0(callid, EOK);
     580                                        /* start answering read calls */
    453581                                        hound_server_write_data(stream);
    454582                                        server_iface->rem_stream(
    … …  
    460588                                if (server_iface->stream_data_write) {
    461589                                        async_answer_0(callid, EOK);
     590                                        /* accept write calls */
    462591                                        hound_server_read_data(stream);
    463592                                        server_iface->rem_stream(
    … …  
    481610}
    482611
     612/**
     613 * Read data and push it to the stream.
     614 * @param stream target stream, will push data there.
     615 */
    483616static void hound_server_read_data(void *stream)
    484617{
    … …  
    487620        size_t size = 0;
    488621        int ret_answer = EOK;
     622        /* accept data write or drain */
    489623        while (async_data_write_receive_call(&callid, &call, &size)
    490624            || (IPC_GET_IMETHOD(call) == IPC_M_HOUND_STREAM_DRAIN)) {
     625                /* check drain first */
    491626                if (IPC_GET_IMETHOD(call) == IPC_M_HOUND_STREAM_DRAIN) {
    492627                        int ret = ENOTSUP;
    … …  
    496631                        continue;
    497632                }
     633
     634                /* there was an error last time */
    498635                if (ret_answer != EOK) {
    499636                        async_answer_0(callid, ret_answer);
    500637                        continue;
    501638                }
     639
    502640                char *buffer = malloc(size);
    503641                if (!buffer) {
    … …  
    507645                const int ret = async_data_write_finalize(callid, buffer, size);
    508646                if (ret == EOK) {
     647                        /* push data to stream */
    509648                        ret_answer = server_iface->stream_data_write(
    510649                            stream, buffer, size);
    … …  
    517656}
    518657
     658/**
     659 * Accept reads and pull data from the stream.
     660 * @param stream target stream, will pull data from there.
     661 */
    519662static void hound_server_write_data(void *stream)
    520663{
    … …  
    524667        size_t size = 0;
    525668        int ret_answer = EOK;
     669        /* accept data read and drain */
    526670        while (async_data_read_receive_call(&callid, &call, &size)
    527671            || (IPC_GET_IMETHOD(call) == IPC_M_HOUND_STREAM_DRAIN)) {
     672                /* drain does not make much sense but it is allowed */
    528673                if (IPC_GET_IMETHOD(call) == IPC_M_HOUND_STREAM_DRAIN) {
    529674                        int ret = ENOTSUP;
    … …  
    533678                        continue;
    534679                }
     680                /* there was an error last time */
    535681                if (ret_answer != EOK) {
    536682                        async_answer_0(callid, ret_answer);
    … …  
    559705 ***/
    560706
     707/**
     708 * Register new hound service to the location service.
     709 * @param[in] name server name
     710 * @param[out] id assigned service id.
     711 * @return Error code.
     712 */
    561713int hound_server_register(const char *name, service_id_t *id)
    562714{
    … …  
    571723}
    572724
     725/**
     726 * Unregister server from the location service.
     727 * @param id previously assigned service id.
     728 */
    573729void hound_server_unregister(service_id_t id)
    574730{
    … …  
    576732}
    577733
     734/**
     735 * Set callback on device category change event.
     736 * @param cb Callback function.
     737 * @return Error code.
     738 */
    578739int hound_server_set_device_change_callback(dev_change_callback_t cb)
    579740{
    … …  
    581742}
    582743
    583 
     744/**
     745 * Walk through all device in the audio-pcm category.
     746 * @param callback Function to call on every device.
     747 * @return Error code.
     748 */
    584749int hound_server_devices_iterate(device_callback_t callback)
    585750{
Note: See TracChangeset for help on using the changeset viewer.