From ea410ba1d3b06ba6f60305c7d31369da134906dd Mon Sep 17 00:00:00 2001 Message-Id: From: Mark Wooding Date: Mon, 24 Sep 2007 12:17:42 +0100 Subject: [PATCH] doxygen + file naming Organization: Straylight/Edgeware From: rjk@greenend.org.uk <> --- lib/Makefile.am | 2 +- lib/{speaker.c => speaker-protocol.c} | 21 ++++- lib/speaker-protocol.h | 116 ++++++++++++++++++++++++++ lib/speaker.h | 60 ------------- server/play.c | 2 +- server/speaker.c | 2 +- 6 files changed, 138 insertions(+), 65 deletions(-) rename lib/{speaker.c => speaker-protocol.c} (79%) create mode 100644 lib/speaker-protocol.h delete mode 100644 lib/speaker.h diff --git a/lib/Makefile.am b/lib/Makefile.am index 4193315..f79435b 100644 --- a/lib/Makefile.am +++ b/lib/Makefile.am @@ -54,7 +54,7 @@ libdisorder_a_SOURCES=charset.c charset.h \ selection.c selection.h \ signame.c signame.h \ sink.c sink.h \ - speaker.c speaker.h \ + speaker-protocol.c speaker-protocol.h \ split.c split.h \ syscalls.c syscalls.h \ types.h \ diff --git a/lib/speaker.c b/lib/speaker-protocol.c similarity index 79% rename from lib/speaker.c rename to lib/speaker-protocol.c index 65bb87d..a362b90 100644 --- a/lib/speaker.c +++ b/lib/speaker-protocol.c @@ -1,6 +1,6 @@ /* * This file is part of DisOrder. - * Copyright (C) 2005 Richard Kettlewell + * Copyright (C) 2005, 2007 Richard Kettlewell * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by @@ -17,6 +17,9 @@ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 * USA */ +/** @file lib/speaker-protocol.c + * @brief Speaker/server protocol support + */ #include #include "types.h" @@ -26,9 +29,14 @@ #include #include -#include "speaker.h" +#include "speaker-protocol.h" #include "log.h" +/** @brief Send a speaker messages + * @param fd File descriptor to send to + * @param sm Pointer to message + * @param datafd File descriptor to pass with message or -1 + */ void speaker_send(int fd, const struct speaker_message *sm, int datafd) { struct msghdr m; struct iovec iov; @@ -59,6 +67,15 @@ void speaker_send(int fd, const struct speaker_message *sm, int datafd) { fatal(errno, "sendmsg"); } +/** @brief Receive a speaker message + * @param fd File descriptor to read from + * @param sm Where to store received message + * @param datafd Where to store received file descriptor or NULL + * @return -ve on @c EAGAIN, 0 at EOF, +ve on success + * + * If @p datafd is NULL but a file descriptor is nonetheless received, + * the process is terminated with an error. + */ int speaker_recv(int fd, struct speaker_message *sm, int *datafd) { struct msghdr m; struct iovec iov; diff --git a/lib/speaker-protocol.h b/lib/speaker-protocol.h new file mode 100644 index 0000000..2002d0b --- /dev/null +++ b/lib/speaker-protocol.h @@ -0,0 +1,116 @@ +/* + * This file is part of DisOrder + * Copyright (C) 2005, 2007 Richard Kettlewell + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, but + * WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software + * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 + * USA + */ +/** @file lib/speaker-protocol.c + * @brief Speaker/server protocol support + * + * This file defines the protocol by which the main server and the speaker + * process communicate. + */ + +#ifndef SPEAKER_H +#define SPEAKER_H + +/** @brief A message from the main server to the speaker, or vica versa */ +struct speaker_message { + /** @brief Message type + * + * Messges from the main server: + * - @ref SM_PREPARE + * - @ref SM_PLAY + * - @ref SM_PAUSE + * - @ref SM_RESUME + * - @ref SM_CANCEL + * - @ref SM_RELOAD + * + * Messages from the speaker: + * - @ref SM_PAUSED + * - @ref SM_FINISHED + * - @ref SM_PLAYING + */ + int type; + + /** @brief Message-specific data */ + long data; + + /** @brief Track ID (including 0 terminator) */ + char id[24]; /* ID including terminator */ +}; + +/* messages from the main DisOrder server */ +/** @brief Prepare track @c id + * + * This message will include a file descriptor. The speaker starts buffering + * audio data read from this file against the time that it must be played. + */ +#define SM_PREPARE 0 + +/** @brief Play track @c id + * + * The track must already have been prepared. + */ +#define SM_PLAY 1 + +/** @brief Pause current track */ +#define SM_PAUSE 2 + +/** @brief Resume current track */ +#define SM_RESUME 3 + +/** @brief Cancel track @c id */ +#define SM_CANCEL 4 + +/** @brief Reload configuration */ +#define SM_RELOAD 5 + +/* messages from the speaker */ +/** @brief Paused track @c id, @c data seconds in + * + * There is no @c SM_RESUMED, instead @ref SM_PLAYING is sent after the track + * starts playing again. + */ +#define SM_PAUSED 128 + +/** @brief Finished playing track @c id */ +#define SM_FINISHED 129 + +/** @brief Currently track @c id, @c data seconds in + * + * This is sent from time to time while a track is playing. + */ +#define SM_PLAYING 131 + +void speaker_send(int fd, const struct speaker_message *sm, int datafd); +/* Send a message. DATAFD is passed too if not -1. Does not close DATAFD. */ + +int speaker_recv(int fd, struct speaker_message *sm, int *datafd); +/* Receive a message. If DATAFD is not null then can receive an FD. Return 0 + * on EOF, +ve if a message is read, -1 on EAGAIN, terminates on any other + * error. */ + +#endif /* SPEAKER_H */ + +/* +Local Variables: +c-basic-offset:2 +comment-column:40 +fill-column:79 +indent-tabs-mode:nil +End: +*/ diff --git a/lib/speaker.h b/lib/speaker.h deleted file mode 100644 index a2da3a5..0000000 --- a/lib/speaker.h +++ /dev/null @@ -1,60 +0,0 @@ -/* - * This file is part of DisOrder - * Copyright (C) 2005 Richard Kettlewell - * - * This program is free software; you can redistribute it and/or modify - * it under the terms of the GNU General Public License as published by - * the Free Software Foundation; either version 2 of the License, or - * (at your option) any later version. - * - * This program is distributed in the hope that it will be useful, but - * WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - * General Public License for more details. - * - * You should have received a copy of the GNU General Public License - * along with this program; if not, write to the Free Software - * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 - * USA - */ - -#ifndef SPEAKER_H -#define SPEAKER_H - -struct speaker_message { - int type; /* message type */ - long data; /* whatever */ - char id[24]; /* ID including terminator */ -}; - -/* messages from the main DisOrder server */ -#define SM_PREPARE 0 /* prepare ID */ -#define SM_PLAY 1 /* play ID */ -#define SM_PAUSE 2 /* pause current track */ -#define SM_RESUME 3 /* resume current track */ -#define SM_CANCEL 4 /* cancel ID */ -#define SM_RELOAD 5 /* reload configuration */ - -/* messages from the speaker */ -#define SM_PAUSED 128 /* paused ID, DATA seconds in */ -#define SM_FINISHED 129 /* finished ID */ -#define SM_PLAYING 131 /* playing ID, DATA seconds in */ - -void speaker_send(int fd, const struct speaker_message *sm, int datafd); -/* Send a message. DATAFD is passed too if not -1. Does not close DATAFD. */ - -int speaker_recv(int fd, struct speaker_message *sm, int *datafd); -/* Receive a message. If DATAFD is not null then can receive an FD. Return 0 - * on EOF, +ve if a message is read, -1 on EAGAIN, terminates on any other - * error. */ - -#endif /* SPEAKER_H */ - -/* -Local Variables: -c-basic-offset:2 -comment-column:40 -fill-column:79 -indent-tabs-mode:nil -End: -*/ diff --git a/server/play.c b/server/play.c index e8df3e8..94567c4 100644 --- a/server/play.c +++ b/server/play.c @@ -47,7 +47,7 @@ #include "eventlog.h" #include "logfd.h" #include "syscalls.h" -#include "speaker.h" +#include "speaker-protocol.h" #include "disorder.h" #include "signame.h" #include "hash.h" diff --git a/server/speaker.c b/server/speaker.c index 2d87e27..2114db4 100644 --- a/server/speaker.c +++ b/server/speaker.c @@ -82,7 +82,7 @@ #include "log.h" #include "defs.h" #include "mem.h" -#include "speaker.h" +#include "speaker-protocol.h" #include "user.h" #include "addr.h" #include "timeval.h" -- [mdw]