Logo Search packages:      
Sourcecode: yiff version File versions  Download package

Ylib.h

/*
                    Y Sound Systems

             Client to Server Library Functions


      All Y client programs needs to #include this file and link to
      the libY2 library.

      For contact and programming information, see:

      http://wolfpack.twu.net/YIFF

 */

#ifndef YLIB_H
#define YLIB_H

#include <stdio.h>
#include <sys/types.h>

#ifdef __cplusplus
extern "C" {
#endif

#include "Y.h"


/*
 *    Volume structure:
 */
typedef struct {

      /* Coefficient = (val / ((u_int16_t)-1)) */

      u_int16_t   left,
                  right,
                  back_left,
                  back_right;

} YVolumeStruct;

/*
 *    Audio CD track structure:
 */
typedef struct {

      int number;       /* Track number, starts from 1 (0 indicates
                         * end of track list when getting track list).
                         */
      unsigned long start_time;     /* In seconds. */
      unsigned long length;         /* In seconds. */
      char name[YAudioCDTrackNameMax];

} YAudioCDTrackStruct;


/*
 *    Event structures:
 */

/* Change mode event structure. */
typedef struct {

      Boolean preset;         /* Use preset? */

      /* If preset is True, these members contain correct info. */
      char mode_name[YAudioNameMax];

      /* If preset is False, these members contain correct info. */
      int sample_size;
      int channels;
      int sample_rate;
      int direction;
      int allow_fragmenting;
      int num_fragments;
      int fragment_size_bytes;

} YEventAudioChange;

/* Y server stats event structure. */
typedef struct {

      int protocol_version_major;
      int protocol_version_minor;
      Coefficient cycle_load;
      unsigned long start_time;

      char vendor_name[YVendorNameMax];   /* Name of Y server vendor. */
      char server_name[YServerNameMax];   /* Name of Y server. */
      char sound_name[YSoundNameMax];           /* Name of Sound device. */

      /* More items to be added in future. */

} YEventServerStats;

/* Change cycle event structure. */
typedef struct {

      long cycle_us;

} YEventCycleChange;

/* Disconnect event structure. */
typedef struct {

      int reason; /* Why you were disconnected. */

} YEventDisconnect;

/* Host add or remove event structure. */
typedef struct {

      int op;           /* 0 for remove, 1 for add. */
      YIPUnion ip;

} YEventHost;

/* Sound kill event structure. */
typedef struct {

      YID yid;

} YEventSoundKill;

/* Mixer event structure. */
typedef struct {

      int code;         /* Mixer device code. */

      Coefficient value[YMixerValues];    /* Argument values. */

} YEventMixer;

/* Sound play event structure. */
typedef struct {

/* These flag definations need to match those of the server. */
#define YPlayValuesFlagYID              (1 << 1)
#define YPlayValuesFlagPosition         (1 << 2)
#define YPlayValuesFlagLength           (1 << 3)
#define YPlayValuesFlagRepeats          (1 << 4)
#define YPlayValuesFlagTotalRepeats     (1 << 5)
#define YPlayValuesFlagVolume           (1 << 6)
#define YPlayValuesFlagSampleRate       (1 << 7)

      unsigned long flags;

      YID yid;

      YDataPosition position;         /* Current play position in bytes. */
      YDataLength length;             /* Length of audio data in bytes. */

      int     repeats,                /* Number of repeats so far. */
            total_repeats;          /* Total number of repeats. */

      Coefficient     left_volume,    /* Volume from 0.0 to 1.0. */
                  right_volume,
                  back_left_volume,
                  back_right_volume;

      int sample_rate;                /* Applied sample rate in Hz. */

} YEventSoundPlay;

/* Sound object attributes event structure. */
typedef struct {

      int format;       /* One of SndObjType*. */
      int sample_size;
      int channels;
      int sample_rate;
      YDataLength length;     /* Length of audio data in bytes. */

      char path[YPathMax];

} YEventSoundObjectAttributes;

/* Shutdown event structure. */
typedef struct {

      int reason; /* Why server shut down. */

} YEventShutdown;

/* Sync event structure. */
typedef struct {

      long cycle_ahead_us;

} YEventSync;

/* Audio stats structure. */ 
typedef struct { 

      int cycle_set;

      long cycle_us;
      long compensated_cycle_us;

      long write_ahead_us;
      long cumulative_latency_us;

      int sample_size;
      int channels;
      int sample_rate;
      int bytes_per_sec;

      Boolean allow_fragments;
      int num_fragments;
      int fragment_size;

      Boolean flip_stereo;
      int direction;

      char mode_name[YAudioNameMax];      /* Can be "" if Audio values were not
                               * set by a preset Audio mode.
                               */

} YEventAudioStats;

/* Client message structure. */
typedef struct {

      int format;       /* One of YClientMessageFormat*. */
      int type;         /* One of YClientMessageType*, note that
                         * clients can also define their own types.
                         * so unexpected values may appear.
                         */
      char message[YClientMessageMessageMax];
      int length;       /* Length of message in bytes. */

} YEventClientMessage;

/* YSHM sound structure. */
typedef struct {

      int minor_op_code;
      int shm_id;
      void *ptr;
      int length;

} YEventYSHMSound;

/* Y Audio CD stats structure. */
typedef struct {

      int minor_op_code;
      int track_number;
      unsigned long track_start_time;
      unsigned long track_length;
      char track_name[YAudioCDTrackNameMax];

} YEventAudioCDStats;

/* Main YEvent structure. */
typedef struct {

      int type;       /* Event type code (aka the major op code). */

      YEventAudioChange audio;
      YEventServerStats serverstats;
      YEventCycleChange cycle;
      YEventDisconnect  disconnect;
      YEventHost        host;
      YEventSoundKill         kill;
      YEventMixer       mixer;
      YEventSoundPlay         play;
      YEventSoundObjectAttributes   sndobjattributes;
      YEventShutdown          shutdown;
      YEventSync        sync;
      YEventAudioStats  audiostats;

      /* New in version 2.14. */
      YEventClientMessage     clientmessage;
      YEventYSHMSound         yshmsound;
      YEventAudioCDStats      audiocdstats;

} YEvent;


/*
 *      Connection to YIFF server structure:
 *
 *    All members here are to be cosidered private.
 */
typedef struct {

      int fd;

      int we_started_server;        /* 1 if we started the Y server. */

      /* Queued events. */
      int total_queued_events;
      YEvent *queued_event;

      YID prev_generated_yid;

      /* Receive buffer. */
      u_int8_t *buf;
      YDataLength     buf_len,        /* Allocated length of buf. */
                  buf_cont;       /* Contents in buf. */

} YConnection;

/*
 *    Audio mode list structure:
 */
typedef struct {

      char name[YAudioNameMax];

      int sample_rate;
      int channels;
      int sample_size;
      int fragment_size_bytes;
      char direction;
      char allow_fragmenting;
      int num_fragments;

} YAudioModeValuesStruct;



/*
 *      Attempts to connect to the Y server at the address and port
 *      specified by con_arg.
 *
 *      con_arg is a null terminated string of the format
 *      "<address>:<port>", ie "127.0.0.1:9433".
 *
 *      If the connect failed and start_arg is not NULL, then
 *      start_arg will be executed as the command to start the
 *      server.  After which a connect attempt will be made again.
 *
 *      Returns a pointer to a YConnection structure or NULL on
 *      error.  To disconnect and deallocate the YConnection structure,
 *      pass it to YIFFDisconnect().
 */
extern YConnection *YOpenConnection(
      const char *start_arg,  /* Can be NULL for don't start if needed. */
      const char *con_arg     /* Can be NULL for default address and port. */
);

/*
 *      Changes the Y server's Audio values.
 *
 *      Note that not all combinations ov values may work, since the
 *      Y server may not support certain combinations of values.  It is
 *      recommended that you use YSetModePreset() whenever possible
 *      since it uses preconfigured values that are known to work.
 *
 *      Returns -1 on failure, and 0 on success.
 */
extern int YSetAudioModeValues(
      YConnection *con,
      int sample_size,
      int channels,
      int sample_rate,
      int direction,          /* 0 = play, only 0 is supported. */
      int allow_fragmenting,
      int num_fragments,
      int fragment_size
);

/*
 *      Changes the Y server's Audio mode to the values specified by
 *      the preset Audio mode who matches the given name.
 *
 *      Returns -1 on failure, and 0 on success.
 */
extern int YChangeAudioModePreset(YConnection *con, const char *name);

/*
 *    Gets Audio device statistics and stores them in the
 *    YEventAudioStats buffer.
 *
 *      Returns -1 on failure, and 0 on success.
 */
extern int YGetAudioStats(YConnection *con, YEventAudioStats *buf);


/*
 *      Gets list of preset Audio modes and their values.
 *
 *      Can return NULL on error.
 */
extern YAudioModeValuesStruct **YGetAudioModes(
      YConnection *con,
      int *count
);

/*
 *      Deletes the list of Audio modes.
 */
extern void YFreeAudioModesList(YAudioModeValuesStruct **list, int count);

/*
 *      Matches an Audio mode with the given values.
 *
 *      If an Audio mode is matched then buf will be set with the
 *      values of the matched Audio mode and True is returned,
 *      otherwise False is returned.
 */
extern Boolean YMatchAudioModeValues(
      YConnection *con,
      YAudioModeValuesStruct *buf,
      int sample_rate,
      int sample_size,
      int channels,
      int direction     /* 0 = play, 1 = record */
);


/*
 *      Gets Y server statistics and stores them in the given
 *      YEventServerStats buffer.
 *
 *      Returns -1 on error and 0 on success.
 */
extern int YGetServerStats(YConnection *con, YEventServerStats *buf);


/*
 *      Calculates the theoretical cycle (in microseconds) for
 *      the Y server given the Audio values.  The Audio values need
 *      not be the current Audio values of the recorder.
 *
 *      If the connection pointer con is NULL, then a general
 *      recommendation answer is returned. This value may not
 *      work with the recorder that you are connected to.
 */
extern long YCalculateCycle(
      YConnection *con,
      int sample_rate, int channels,
      int sample_size, int fragment_size
);

/*
 *      Set cycle in microseconds.
 *
 *      Returns -1 on error and 0 on success.
 */
extern int YSetCycle(YConnection *con, long us);

/*
 *      Syncs all of the Y server's resources, both the Y server and the
 *      client will also be synced.
 *
 *      If block is True then this operation will block (in finite time)
 *      to ensure that the Y server is up to sync.
 */
extern void YSyncAll(YConnection *con, Boolean block);


/*
 *      Adds the IP address specified by ip to the Y server's access
 *    list.
 *
 *      Returns -1 on failure, and 0 on success.
 */
extern int YAddHost(YConnection *con, YIPUnion *ip);

/*
 *    Removes the IP address specified by ip from the Y server's
 *    access list. If the specified ip does not exist in the Y server's
 *    access list then no operation will be performed.
 *
 *    Returns -1 on failure, and 0 on success.
 */
extern int YRemoveHost(YConnection *con, YIPUnion *ip);

/*
 *      Sets specified mixer channel values.
 *
 *      Returns -1 on failure, and 0 on success.
 */
extern int YSetMixerChannel(
      YConnection *con,
      int mixer_channel_code,       /* One of YMixerCode*. */
      Coefficient value1, Coefficient value2    /* 0.0 to 1.0. */
);
extern int YSetMixerChannelQuad(
      YConnection *con,
      int mixer_channel_code,
      Coefficient value1, Coefficient value2,   /* 0.0 to 1.0. */
      Coefficient value3, Coefficient value4    /* 0.0 to 1.0. */
);


/*
 *      Gets specified mixer channel values.
 *
 *      Returns -1 on failure, and 0 on success.
 */
extern int YGetMixerChannel(
      YConnection *con,
      int mixer_channel_code,       /* One of YMixerCode*. */
      Coefficient *value1, Coefficient *value2  /* 0.0 to 1.0. */
);
extern int YGetMixerChannelQuad(
      YConnection *con,
      int mixer_channel_code,
      Coefficient *value1, Coefficient *value2, /* 0.0 to 1.0. */
      Coefficient *value3, Coefficient *value4  /* 0.0 to 1.0. */
);


/*
 *      Starts playing the sound object specified by path, returns
 *      the YID identifying the sound object being played or YIDNULL on
 *      failure.
 */
extern YID YStartPlaySoundObjectSimple(
      YConnection *con,
      const char *path  /* Path on disk on server's computer. */
);

/*
 *      Starts playing the sound object specified by path, returns
 *      the YID indentifying the sound object being played or YIDNULL on
 *      failure.
 *
 *      The only criteria for a success here is that the sound object
 *      exist.
 */
extern YID YStartPlaySoundObject(
      YConnection *con,
      const char *path, /* Path on disk on server's computer. */
      YEventSoundPlay *value
);

/*
 *      Gets sound object attributes, returns -1 on error or
 *      0 on success.
 *
 *      Note, the sound object need not be playing in order to
 *      fetch its attributes.
 */
extern int YGetSoundObjectAttributes(
      YConnection *con, const char *path,
      YEventSoundObjectAttributes *buf
);

/*
 *      Modifies the play values of the sound object specified by yid
 *      that is already playing.
 */
extern void YSetPlaySoundObjectValues(
      YConnection *con, YID yid, YEventSoundPlay *value
);

/*
 *    Gets the play values of the sound object specified by yid
 *      that is already playing.
 *
 *    Returns 0 on success and non-zero on error.
 */
extern int YGetPlaySoundObjectValues(
      YConnection *con, YID yid, YEventSoundPlay *value
);

/*
 *      Destroys (stops/kills/terminates) the sound object
 *      being played, indetified by yid. If the yid does not
 *      match any sound object currently being played, no
 *      operation will be performed.
 */
extern void YDestroyPlaySoundObject(YConnection *con, YID yid);


/*
 *    Sends a client message.
 *
 *      Returns -1 on failure, and 0 on success.
 */
extern int YSendClientMessage(
      YConnection *con,
      Boolean notify_self,    /* Send ourself this YClientMessage event too. */     
      int format,       /* One of YClientMessageFormat*. */
      int type,         /* One of YClientMessageType*, note that
                         * clients can also define their own types.
                         * so unexpected values may appear.
                         */
      const char *message,    /* Message. */
      int length        /* Length of message in bytes. */
);


/*
 *      Opens the shared memory segment of the sound buffer on the Y
 *      server.
 *
 *      Returns the pointer to the memory segment, the length of the
 *      buffer in bytes, and the shared memory segment id.
 *
 *      The returned pointer must be closed by calling YSHMClose().
 *
 *      Can return NULL on error.
 */
extern void *YSHMOpenSound(YConnection *con, int *length, int *id);

/*
 *      Closes the shared memory segment of the sound buffer that was
 *      previously opened by a call to YSHMOpenSound().
 */
extern void YSHMCloseSound(YConnection *con, void *ptr);


/*
 *    Plays audio CD track specified by track_number.
 *
 *      Returns -1 on failure, and 0 on success.
 */
extern int YPlayAudioCDTrack(YConnection *con, int track_number);

/*
 *    Stops audio CD playing.
 *
 *      Returns -1 on failure, and 0 on success.
 */
extern int YStopAudioCD(YConnection *con);

/*
 *    Ejects audio CD.
 *
 *      Returns -1 on failure, and 0 on success.
 */
extern int YEjectAudioCD(YConnection *con);


/*
 *      Gets list of Audio CD tracks.
 *
 *      Can return NULL on error.
 */
extern YAudioCDTrackStruct **YGetAudioCDTracks(
      YConnection *con, int *count
);

/*
 *      Deallocates the list of Audio CD track structures and the
 *      pointer array.
 */
extern void YFreeAudioCDTracksList(YAudioCDTrackStruct **list, int count);


/*
 *      Disconnects from YIFF server and frees all allocated
 *      resources.
 *
 *      The pointer con may no longer be used after a call to this
 *      function.
 */
extern void YCloseConnection(YConnection *con, Boolean no_shutdown);

/*
 *      Shuts down the YIFF server, thus disconnecting and
 *      freeing all allocated resources.
 *
 *      The pointer con may no longer be used after a call to this
 *      function.
 */
extern void YShutdownServer(YConnection *con);


/*
 *      Get next (oldest) event from the server and stores it on
 *      the pointer to the YEvent event.
 *
 *      If block is set to True, then execution will be
 *      blocked untill next event is recieved.
 *
 *      If the recieved event is of type YDisconnect or YShutdown then
 *      the given con structure's connection descriptor will be closed
 *      and reset to -1.
 *
 *    Returns positive if an event is fetched.
 */
extern int YGetNextEvent(
      YConnection *con,
      YEvent *event,
      Boolean block
);

/*
 *      Puts back the event onto the queue as the newest (highest
 *      index) event.
 *
 *      So all other older events (if any) will be returned before this
 *      one when YGetNextEvent() is called.
 */
extern void YPutBackEvent(YConnection *con, YEvent *event);


#ifdef __cplusplus
}
#endif

#endif      /* YLIB_H */

Generated by  Doxygen 1.6.0   Back to index