The OpenSMDI Library Manual

 Christian Nowak, chnowak@web.de
v0.05b, 06 September 2000
This document describes how to use the SMDI library in your own programs in order to transfer digital sound samples from and to a sampler via SMDI through an SCSI connection. It contains all neccessary commands to receive, send, delete and rename samples, whereby it doesn't matter which language you use or what file formats you are dealing with.

Table Of Contents

1. Introduction

This is the SMDI library manual. It is intended as a quick overview over the concepts of SMDI and SCSI. Moreover, it is a description of all functions and structures which are used in the library.

1.1. Revision History

Version 0.01a
First version with documentation in Microsoft Word format
Version 0.02a
Re-written documentation in the platform-independent HTML format. Some structures have changed and new functions were added.
Version 0.03b
The library has been ported to Linux.
Version 0.04b
Threading under Linux
Support for more than one host adapter
Minor cleanup in the source
Version 0.05b
Compiler support for MS VC++ and the free Borland C++ compiler
The SMDI_SendFile and SMDI_ReceiveFile functions now accept an argument dwUserData which is passed to the callback function
These functions have now reached their final definitions by accepting their arguments in a structure

1.2. New Versions Of This Document

New versions of this document will be uploaded to the main site of the whole library which is at http://www.teklab.com/openSMDI/. They will also be uploaded to various anonymous ftp sites that archive such libraries including ftp://ftp.simtel.net.

1.3. Feedback

I rely on you, the users, to make this document and the entire library useful. If you have any suggestions, corrections, or comments, please send them to me, chnowak@web.de, and I will try to incorporate them in the next revision.

I am also willing to answer general questions on SMDI, SCSI and using the library, as best as I can. Before doing so, please read all of the information in this manual, and send me detailed information about the problem.

If you publish this document or the entire library on a CD-ROM or in hardcopy form, a complimentary copy would be appreciated.

1.4. Distribution Policy

Copyright (C) 1999, 2000 Christian Nowak.

This document is free documentation; 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 document 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 can obtain a copy of the GNU General Public License by writing to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

2. The SCSI Standard

"SCSI is a local I/O bus that can be operated over a wide range of data rates. The primary objective of the interface is to provide host computers with device independence within a class of devices. Thus, different disk drives, tape drives, printers, optical media drives, and other devices can be added to the host computers without requiring modifications to generic system hardware or software. Provision is made for the addition of special features and functions through the use of vendor unique fields and codes. Reserved fields and codes are provided for future standardization."
 (Small Computer System Interface 2 draft Revision 10b, American National Standard)

You can purchase a copy of the whole draft via paper mail from:
Global Engineering Documents
2805 McGaw, Irvine, CA 92714
In practice, the SCSI interface in PCs is nowadays provided by SCSI host adapters, such as the Adapted AVA-15xx series, which can either be a slot card (PCI or ISA), or an adapter for the parallel port or the PC-Card slot of today's notebooks. A normal SCSI host adapter can manage up to 8 or 16 different devices in one chain, whereby the first and the last device must be terminated. This basically means that the chain must be electrically "closed" on both ends by putting a resistor at the end in order to avoid electrical interferences in the signals. Each device in a chain must have its own number so that it can be specified when it's accessed by any other device. The SCSI host adapter in the PC also has its own SCSI ID. As stated above, there are many different device classes like tape drives, printers, optical media drives and so on. Samplers and computers belong to the processor device class. All devices in one class can always be accessed in the same way. All the intelligence to access data is implemented in the device itself and not in the PC as drivers.

3. The SMDI Protocol

Since samplers are naturally processor devices in SCSI's terminology, you can only send and receive strings of bytes to/from them. It's the way you format the bytes in one string what determines whether you're communicating with the sampler in the SMDI "language". These strings are called messages, and they're exchanged in an alternating way. So, the computer sends a message to the sampler, and the sampler answers with a message.
Each message is divided into 3 different parts:
1. The SMDI message tag, a fixed four-byte string "SMDI", which serves as an identifying tag for all SMDI messages.
2. The message code, which identifies the type of the message and consists of a two-byte Message ID code, followed by a two-byte Message Sub-ID code.
3. The Additional Message Length, a three-byte field which indicates the number of bytes following the header in the current message.

4. Usage Of The SMDI Library

Under Win32 Based Systems

It is recommended to dynamically link with the smdi.dll under windows. You do this by calling the API's LoadLibrary function to open the library and then calling the GetProcAddress function to get the start address of a desired OpenSMDI function. Here's a small C snippet which does this:

#include "smdidynamic.h"

/* Open the library */
HINSTANCE hSmdiDll = LoadLibrary ( "smdi.dll" );
if (hSmdiDll == NULL)
{
printf ("Couldn't open smdi.dll !\nError code: %d\n",GetLastError());
return(1);
}


/* Getting the function addresses */
SMDI_Init = GetProcAddress ( hSmdiDll, "SMDI_Init" );
if (SMDI_Init == NULL) SMDI_Init = GetProcAddress ( hSmdiDll, "_SMDI_Init" );

SMDI_MasterIdentify = GetProcAddress ( hSmdiDll, "SMDI_MasterIdentify" );
if (SMDI_MasterIdentify == NULL) SMDI_MasterIdentify = GetProcAddress ( hSmdiDll, "_SMDI_MasterIdentify" );

/* Calling the functions */
if (SMDI_Init() > 0)
printf("ha 0, id 0 SMDI Master Identify response: 0x%x\n", SMDI_MasterIdentify ( 0, 0 ));

/* Closing the library */
FreeLibrary ( &hSmdiDll );

Since some compilers export function names with a preceding underscore (_) into the dll and others don't, it is strongly recommended to support at least these both versions of the function names. Be as liberal with what function names you're importing as possible !
If you're going to link with smdi.dll statically, #include the smdistatic.h file, when linking dynamically, use smdidynamic.h, and if you just need the constant and struct definitions, use smdi.h.

Under Linux

If you're using c (GCC, for example), just link the library with your executable and include the file SMDI.H into your source.
Compiling is done like this:
gcc test.c smdi.so.1 -o test
Please note that the SCSI-ID parameter which is used by some structures and many functions is actually an index to the generic device driver ("/dev/sg[a-n]") under Linux. Therefore, an SCSI-ID of 0 means /dev/sga and 5 means /dev/sgf. This only applies to Linux, where these device files are dynamically mapped to the SCSI id's. Therefore, assuming you had hooked up three SCSI devices with id's 1, 3 and 5, then the following mapping would be in effect:
/dev/sga -> id 1 (SCSI-ID param = 0)
/dev/sgb -> id 3 (SCSI-ID param = 1)
/dev/sgc -> id 5 (SCSI-ID param = 2)

4.1. Structure Definitions

By now, there are five different structures in the SMDI library. I'll use the original C declarations here. Structure members with the name Rsvd are reserved for DWORD aligning and will possibly be used in future versions of the library. Every structure has a member dwStructSize. Before you use any structure, you'll have to enter here the size of the entire structure in bytes, including dwStructSize itself.

In C, you do this with:
whateverstructure.dwStructSize = sizeof(whateverstructure);

In Delphi, you do this with:
whateverstructure.dwStructSize := SizeOf(whateverstructure);

4.1.1. SCSI_DevInfo

Description

The SCSI_DevInfo structure contains information which the SMDI_GetDeviceInfo function returns information about an SCSI device, if it is SMDI compatible.

Definition

typedef struct SCSI_DevInfo
{
DWORD dwStructSize;
BOOL bSMDI;
BYTE DevType;
BYTE Rsvd1;
BYTE Rsvd2;
BYTE Rsvd3;
char cName[20];
char cManufacturer[12];
} SCSI_DevInfo;

Members

bSMDI
TRUE if the device is SMDI compatible.
DevType
The type of the SCSI device. If bSMDI is true, this one should always be 3 (=processor device).
cName
The device's name.
cManufacturer
The device's manufacturer.

4.1.2. SMDI_SampleHeader

Description

This structure contains information about a sample returned by SMDI_SampleHeaderRequest and SMDI_GetFileSampleHeader.

Definition

typedef struct SMDI_SampleHeader
{
DWORD dwStructSize;
BOOL bDoesExist;
BYTE BitsPerWord;
BYTE NumberOfChannels;
BYTE LoopControl;
BYTE NameLength;
DWORD dwPeriod;
DWORD dwLength;
DWORD dwLoopStart;
DWORD dwLoopEnd;
WORD wPitch;
WORD wPitchFraction;
char cName[256];
DWORD dwDataOffset;
} SMDI_SampleHeader;

Members

bDoesExist
After a call of SMDI_SampleHeaderRequest or SMDI_GetFileSampleHeader, this one specifies whether the sample does exist at the given location or not.
BitsPerWord
Bits used for a single sample. Usually 8 or 16.
NumberOfChannels
The number of channels the sample uses. 2 is stereo and 1 is mono.
LoopControl
Specifies if and how the defined loop between dwLoopStart and dwLoopEnd should be played.
NameLength
Length of the sample's name, in bytes.
dwPeriod
The length of a period of one single sample frame in nanoseconds. The frequency is f = 10^9 / dwPeriod
dwLength
Length of the sample, measured in sample frames. One sample frame's length is (NumberOfChannels*BitsPerWord)/8 bytes.
dwLoopStart
The sample frame's number where the loop starts.
dwLoopEnd
The sample frame's number where the loop stops.
wPitch
Indicates the absolute musical pitch of the sound represented by the sample when played at the specified sample rate. This integer specifies a specific semitone (60 is middle C).
wPitchFraction
Specifies the fine tuning of the sound, measured in cents upward from the semitone. 60.00 is exactly middle C, 60.32768 is 50 cents above middle C. In the case that the two pitch values are unavailable, a default of 60.00 should be used.
cName
Name of the sound.
dwDataOffset
After a call of SMDI_GetFileSampleHeader, this value determines the offset from the beginning of the given file, where the sample data begins.

4.1.3. SMDI_TransmissionInfo

Description

This structure contains information about a current tranfer from/to a sampler.

Definition

typedef struct SMDI_TransmissionInfo
{
DWORD dwStructSize;
SMDI_SampleHeader * lpSampleHeader;
DWORD dwTransmittedPackets;
DWORD dwPacketSize;
DWORD dwSampleNumber;
DWORD dwCopyMode;
void * lpSampleData;
BYTE SCSI_ID;
BYTE HA_ID;
BYTE Rsvd1;
BYTE Rsvd2;
} SMDI_TransmissionInfo;

Members

lpSampleHeader
Pointer to a SMDI_SampleHeader structure which contains information about the sample which is currently being transmitted.
dwTransmittedPackets
The number of packets which have already been transmitted.
dwPacketSize
Size of each packet, measured in bytes. This value must be aligned so that no sample frames are getting fragmented, for example a multiple of 4 for 16 bit stereo samples and a mutliple of 2 for 8 bit stereo samples.
dwSampleNumber
The memory location within the sampler where a sample is currently sent to or received to.
dwCopyMode
In SMDI transfers, word and doubleword values are stored in the Motorola (MSB, .., LSB) format and not in the Intel (LSB, .., MSB) format, making it neccessary to swap the bytes of each sample frame in order to make the data readable for Intel processors. This value specifies if and how the data which is received or sent is byte swapped. You can choose any of the 3 available Copymodes constants.
lpSampleData
Pointer to a piece of memory which contains the next data packet to be sent or which will receive the next data packet. The size of this piece of memory must be at least dwPacketSize.
SCSI_ID
The SCSI number of the currently accessed device.
HA_ID
The host adapter number to which the device is attached.

4.1.4. SMDI_FileTransmissionInfo

Description

This structure contains information about the sample file which is currently being sent or received.

Definition

typedef struct SMDI_FileTransmissionInfo
{
DWORD dwStructSize;
FARPROC lpCallBackProcedure;
SMDI_TransmissionInfo * lpTransmissionInfo;
DWORD dwFileType;
HANDLE hFile;
char cFileName[MAX_PATH];
} SMDI_FileTransmissionInfo;

Members

lpCallbackProcedure
In transfers using SMDI_SendFile or SMDI_ReceiveFile, this member contains a pointer to a procedure which is called after each transmission of a packet. If it is NULL, no procedure is being called.
lpTransmissionInfo
A pointer to a SMDI_TransmissionInfo structure.
dwFileType
The sample file type which is currently being read from or written to. You can choose any of the available file type constants.
hFile
Handle of the currently opened file.
cFileName
Name of the currently opened file.

4.1.5. SMDI_FileTransfer

Description

This structure is used by the functions SMDI_SendFile and SMDI_ReceiveFile for accepting their arguments.

Definition

typedef struct SMDI_FileTransfer
{
DWORD dwStructSize;
BYTE HA_ID;
BYTE rsvd1;
BYTE rsvd2;
BYTE rsvd3;
BYTE SCSI_ID;
BYTE rsvd4;
BYTE rsvd5;
BYTE rsvd6;
DWORD dwSampleNumber;
char * lpFileName;
DWORD dwFileType;
char * lpSampleName;
void (*lpCallback)();
DWORD dwUserData;
BOOL bAsync;
DWORD * lpReturnValue;
} SMDI_FileTransfer;

Members

HA_ID
The host adapter number to which the device is attached.
SCSI_ID
The device's SCSI ID.
dwSampleNumber
The memory location in the sampler where the sample shall be sent to or received from.
lpFileName
Specifies the file on the local computer which shall be sent or stored.
dwFileType
Determines the format of the file which is stored. Can be any of the file type constants. Only needed when receiving a sample.
lpSampleName
The name of the sample. Only needed when sending a sample.
lpCallback
Enter a pointer to a function here. It is called each time a data packet has been sent or received from/to the sampler. If you don't want a function to be called, you can enter NULL. As the first parameter, a pointer to a SMDI_FileTransmissionInfo structure will be passed to the Callback function.
dwUserData
This value will be passed as the second argument to the callback function. It can be anything.
bAsync
If this one is TRUE, the main procedure which sends or receives the sample is threaded. This means that SMDI_SendFile or SMDI_ReceiveFile will return immediately and the process of sending or receiving the sample is executed in the background.
lpReturnValue
If bAsync is TRUE and lpReturnValue not NULL, the DWORD to which lpReturnValue points will be -1 and after the transmission is finished, it will contain the return value.

4.2. Constants

This section describes all constants used in the library.

4.2.1. SMDI Messages

SMDIM_MESSAGEREJECT

Sent by the sampler when an error occured. The bytes 11-14 of the reject message contains extended error information.

SMDIM_SENDNEXTPACKET

Sent by the sampler when it's awaiting the next data packet in a sample transmission.

SMDIM_ENDOFPROCEDURE

Sent by the sampler when a procedure has successfully been finished.

SMDIM_ABORTPROCEDURE

Can be sent by either the computer or the sampler to abort a procedure.

SMDIM_DATAPACKET

A data packet message. Contains a data packet.

SMDIM_SAMPLEHEADERREQUEST

Sent by the computer to request a sample header. The expected reply is SMDIM_SAMPLEHEADER.

SMDIM_SAMPLEHEADER

Identifies a sample header message, which contains information about a sample.

SMDIM_SAMPLENAME

The sample name message, sent to the sampler in order to rename a sample.

SMDIM_DELETESAMPLE

The delete sample message, sent to the sampler in order to delete a sample.

SMDIM_BEGINSAMPLETRANSFER

Sent to the sampler in order to begin a sample transfer in either direction. The expected reply is SMDIM_TRANSFERACKNOWLEDGE.

SMDIM_TRANSFERACKNOWLEDGE

Used to acknowledge a sample transfer in either direction.

SMDIM_TRANSMITMIDIMESSAGE

Can be used to transmit MIDI strings to the sampler.

4.2.2. SMDI Errors

SMDI error constants represent error codes transmitted within a SMDIM_MESSAGEREJECT message by the sampler.

SMDIE_OUTOFRANGE

A sample location within the sampler has been tried to accessed, which is out of the sampler's range.

SMDIE_NOSAMPLE

A sample header or an entire sample has been requested from a location in the sampler where there is no sample.

SMDIE_NOMEMORY

It has been tried to send a sample to the sampler which is too big to fit into the sampler's memory.

SMDIE_UNSUPPSAMBITS

It has been tried to send a sample to the sampler with a bit whidth which isn't supported by the sampler.

4.2.3. Copy Modes

Copy modes specify if and how sample data should be byte swapped in transfers.

CM_NORMAL

The data isn't swapped at all.

CM_SWAPDWORD

4 bytes are always swapped. 0x11223344 will get 0x44332211.

CM_SWAPWORD

2 bytes are always swapped. 0x1122 will get 0x2211.

4.2.4. File Types

The file type constants determine the file formats which the library does support.

FT_WAV

The Windows RIFF WAVE format.

4.2.5. File Errors

Error codes in functions which handle files.

FE_OPENERROR

The specified file couldn't be opened. Most probably it doesn't exist.

FE_UNKNOWNFORMAT

The specified is of an unknown, unsupported format.

4.3. Command Reference

This section describes all important Functions available in the library.

4.3.1. SMDI_GetVersion

Description

The SMDI_GetVersion function returns the version number of the currently used copy of the SMDI library.

Definition

DWORD SMDI_GetVersion ( void );

Return Values

The version number of the currently used copy of the SMDI library, in percent. For example, 4 is v0.04 and 123 is v1.23. Pre-releases, such as v1.23.4, are returned as v1.23.

4.3.2. SMDI_Init

Description

The SMDI_Init function resets the SCSI bus, if there is one.

Definition

BYTE SMDI_Init ( void );

Return Values

If it succeeded, it returns the number of host adapters in the system. If it returns 0, there are no host adapters. Under Linux it always returns 1.

4.3.3. SMDI_GetDeviceInfo

Description

The SMDI_GetDeviceInfo function retrieves information about the SCSI device with the given ID.

Definition

void SMDI_GetDeviceInfo ( BYTE HA_ID, BYTE SCSI_ID, SCSI_DevInfo * lpDevInfo );

Parameters

HA_ID
The host adapter number to which the device is attached.
SCSI_ID
The device's SCSI ID.
lpDevInfo
A pointer a SCSI_DevInfo structure which will be filled with the information about the desired device. Note that, if the bSMDI member of the structure is FALSE after the call, all other members are invalid.

4.3.4. SMDI_SendFile

Description

The SMDI_SendFile function sends a sample from a local file to a sampler. The local file can be in any format which is supported by the library.

Definition

DWORD SMDI_SendFile ( SMDI_FileTransfer * lpFileTransfer);

Parameters

lpFileTransfer
A pointer to a SMDI_FileTransfer structure which contains all necessary arguments.

Return Values

Id the SMDI_SendFile function has been called with bAsync being TRUE, the expected return value is -1 (0xffffffff). This means that the transmission is being started. If bAsync is FALSE, the expected return value is one of the following:
SMDIM_ENDOFPROCEDURE
SMDIE_OUTOFRANGE
SMDIE_NOMEMORY
SMDIE_UNSUPPSAMBITS
FE_OPENERROR
FE_UNKNOWNFORMAT

Remarks

Internally, this function uses the functions SMDI_InitFileSampleTransmission and SMDI_FileSampleTransmission.

See Also

SMDI_ReceiveFile

4.3.5. SMDI_ReceiveFile

Description

The SMDI_ReceiveFile function receives a sample from a sampler and stores it into a local file. The local file can be in any format which is supported by the library.

Definition

DWORD SMDI_ReceiveFile ( SMDI_FileTransfer * lpFileTransfer );

Parameters

lpFileTransfer
A pointer to a SMDI_FileTransfer structure which contains all necessary arguments.

Return Values

If the SMDI_ReceiveFile function is called with bAsync being TRUE, the expected return value is -1 (0xffffffff). This means that the transmission ist started. If bAsync is FALSE, the return value is one of the following:
SMDIM_ENDOFPROCEDURE
SMDIE_OUTOFRANGE
SMDIE_NOSAMPLE
FE_OPENERROR
FE_UNKNOWNFORMAT

Remarks

Internally, this function uses the functions SMDI_InitFileSampleReception and SMDI_FileSampleReception.

See Also

SMDI_SendFile

4.3.6. SMDI_InitFileSampleTransmission

Description

The SMDI_InitFileSampleTransmission function initiates a sample transmission from the computer to the sampler by checking the format of the file entered in the SMDI_FileTransmissionInfo structure which is passed to this function and sending all neccessary information to the sampler. The return value determines whether the transmission can be continued using the SMDI_FileSampleTransmission function or not.

Definition

DWORD SMDI_InitFileSampleTransmission ( SMDI_TransmissionInfo * lpFileTransmissionInfo);

Parameters

lpFileTransmissionInfo
A pointer to a SMDI_FileTransmissionInfo structure. The following members of the structure have to be filled before calling this function:
lpTransmissionInfo
cFileName
In the SMDI_TransmissionInfo structure, whose address is enterd in lpTransmissionInfo, the following members must be filled before calling the function:
lpSampleHeader
dwSampleNumber

Return Values

The expected return value is SMDIM_SENDNEXTPACKET. If an error occured, other possible return values are:
FE_OPENERROR
FE_UNKNOWNFORMAT
SMDIE_OUTOFRANGE
SMDIE_NOMEMORY
SMDIE_UNSUPPSAMBITS

Remarks

Internally, this function uses the SMDI_InitSampleTransmission function and only adds support for file formats.

See Also

SMDI_FileSampleTransmission

4.3.7. SMDI_FileSampleTransmission

Description

The SMDI_FileSampleTransmission function must be called after a successful call of the SMDI_InitFileSampleTransmission function. On each call, it sends the next data packet from the file to the sampler until there are no more packets to send.

Definition

DWORD SMDI_FileSampleTransmission ( SMDI_FileTransmissionInfo * lpFileTransmissionInfo );

Parameters

lpFileTransmissionInfo
A pointer to the SMDI_FileTransmissionInfo structure which has been used in the call of SMDI_InitFileSampleTransmission.

Return Values

The expected return value is SMDIM_SENDNEXTPACKET. This means that the sampler is awaiting the next packet and you have to call the SMDI_FileSampleTransmission function again. If the sample transfer has ended successfully, the expected return value is SMDIM_ENDOFPROCEDURE. In this case, you must not call this function again.

Remarks

Internally, this function uses the SMDI_SampleTransmission function and only adds support for file formats.

See Also

SMDI_InitFileSampleTransmission

4.3.8. SMDI_InitFileSampleReception

Description

The SMDI_InitFileSampleReception initiates a sample transmission from the sampler to the computer by receiving the sample information from the sampler and writing the header of a local file whose name and format is entered in the SMDI_FileTransmissionInfo structure. The return value determines whether the transmission can be continued via the SMDI_FileSampleReception function or not.

Definition

DWORD SMDI_InitFileSampleReception ( SMDI_FileTransmissionInfo * lpFileTransmissionInfo );

Parameters

lpFileTransmissionInfo
A pointer to a SMDI_FileTransmissionInfo structure. The following members of the structure have to be filled before calling this function:
lpTransmissionInfo
dwFileType
cFileName
dwFileType can be any of the file type constants.
The following members of the SMDI_TransmissionInfo structure whose address is entered into lpTransmissionInfo must be filled:
lpSampleHeader
dwSampleNumber
SCSI_ID

Return Values

The expected return value is SMDIM_TRANSFERACKNOWLEDGE. This means that the sampler is ready to send the next data packet and you have to call the SMDI_FileSampleReception function. If an error occured, other possible return values are:
SMDIE_OUTOFRANGE
SMDIE_NOSAMPLE
FE_OPENERROR
FE_UNKNOWNFORMAT

Remarks

Internally, this function uses the SMDI_InitSampleReception function.

See Also

SMDI_FileSampleReception

4.3.9. SMDI_FileSampleReception

Description

The SMDI_FileSampleReception function must be called after a successful call of the SMDI_InitFileSampleReception function. On each call, it receives the next data packet from the sampler and stores it into the file until there are no more packets to receive.

Definition

DWORD SMDI_FileSampleReception ( SMDI_FileTransmissionInfo * lpFileTransmissionInfo );

Parameters

lpFileTransmissionInfo
A pointer to the SMDI_FileTransmissionInfo structure which has been used in the call of SMDI_InitFileSampleReception.

Return Values

The expected return value is SMDIM_DATAPACKET. This means that the data packet has been received and stored into the local file successfully and that the sampler is ready to send the next one. In this case, you have to call the SMDI_FileSampleReception function again. If the sample transfer has ended successfully, the expected return value is SMDIM_ENDOFPROCEDURE. In this case, you must not call this function again.

Remarks

Internally, this function uses the SMDI_SampleReception function and only adds support for file formats.

See Also

SMDI_InitFileSampleReception

4.3.10. SMDI_InitSampleTransmission

Description

The SMDI_InitSampleTransmission initiates a sample transmission from the computer to the sampler.

Definition

unsigned long SMDI_InitSampleTransmission ( SMDI_TransmissionInfo * lpTransmissionInfo );

Parameters

lpTransmissionInfo
A pointer to a SMDI_TransmissionInfo structure. Before you call this function, you have to fill the following members of the structure:
lpSampleHeader
dwPacketSize
dwSampleNumber
dwCopyMode
SCSI_ID
The lpSamplerHeader member should be filled with the address of a filled SMDI_SampleHeader structure.
The dwPacketSize member should be filled with a suggested packet size in bytes, for example 16384 or 65536.

Return Values

The expected return value is SMDIM_SENDNEXTPACKET. If an error occured, other possible return values are:
SMDIE_OUTOFRANGE
SMDIE_NOMEMORY
SMDIE_UNSUPPSAMBITS
If this function returned SMDIM_SENDNEXTPACKET, the dwPacketSize member of the SMDI_TransmissionInfo structure contains the size of each packet in bytes. Before you call the SMDI_SampleTransmission function, you'll have to allocate at least that much memory and enter its address into the lpSampleData member of the structure. Before each call of SMDI_SampleTransmission you'll have to re-fill this memory with the sample data of the next data packet.

4.3.11. SMDI_SampleTransmission

Description

The SMDI_SampleTransmission function transmits the next data packet, whose size is stored in the dwPacketSize and address in the lpSampleData member of the SMDI_TransmissionInfo structure, from the computer to the sampler after a call of SMDI_InitSampleTransmission.

Definition

DWORD SMDI_InitSampleTransmission ( SMDI_TransmissionInfo * lpTransmissionInfo );

Parameters

lpTransmissionInfo
A pointer to the SMDI_TransmissionInfo structure which has been used in all previous calls of SMDI_SampleTransmission and SMDI_InitSampleTransmission.

Return Values

The expected return value is SMDIM_SENDNEXTPACKET if there's one more packet to send. In this case, you have to call this function again. In the case that the return value is SMDIM_ENDOFPROCEDURE, the sample has been send successfully and you must not call this function again.

See Also

SMDI_InitSampleTransmission

4.3.12. SMDI_InitSampleReception

Description

The SMDI_InitSampleReception function initiates a sample transmission from the sampler to the computer.

Definition

DWORD SMDI_InitSampleReception ( SMDI_TransmissionInfo * lpTransmissionInfo );

Parameters

lpTransmissionInfo
A pointer to a SMDI_TransmissionInfo structure.
Before a call of this function, you have to enter the following members of the structure:
lpSampleHeader
dwSampleNumber
dwCopyMode
SCSI_ID

Return Values

The expected return value is SMDIM_TRANSFERACKNOWLEDGE. This means that the sampler is ready to send the next data packet. You'll then have to call the SMDI_SampleReception function. If an error occurred, other possible return values are:
SMDIE_OUTOFRANGE
SMDIE_NOSAMPLE

See Also

SMDI_SampleReception

4.3.13. SMDI_SampleReception

Description

The SMDI_SampleReception function transmits the next data packet, whose size is stored in the dwPacketSize and address in the lpSampleData member of the SMDI_TransmissionInfo structure, from the sampler to the computer after a call of SMDI_InitSamplereception.

Definition

DWORD SMDI_SampleReception ( SMDI_TransmissionInfo * lpTransmissionInfo );

Parameters

lpTransmissionInfo
A pointer to the SMDI_TransmissionInfo structure which has been used in all previous calls of SMDI_SampleReception and SMDI_InitSampleReception.

Return Values

The expected return value is SMDIM_DATAPACKET. This means that the data packet has successfully been received and stored into the memory whose address is stored in the lpSampleData member of the SMDI_TransmissionInfo structure, and that the sampler is ready to send the next one. If the sample transfer has ended successfully, the expected return value is SMDIM_ENDOFPROCEDURE. In this case, you must not call this function again.

See Also

SMDI_InitSampleReception

4.3.14. SMDI_SampleHeaderRequest

Description

The SMDI_SampleHeaderRequest function receives information about a sample in a specified memory location of a specified sampler.

Definition

DWORD SMDI_SampleHeaderRequest ( BYTE HA_ID, BYTE SCSI_ID, DWORD dwSampleNumber, SMDI_SampleHeader * lpSampleHeader );

Parameters

HA_ID
The host adapter number to which the device is attached.
SCSI_ID
The device's SCSI ID.
dwSampleNumber
The memory location in the sampler where the sample about which you want to have information is stored.
lpSampleHeader
A pointer to a SMDI_SampleHeader structure which will be filled with the sample information.

Return Values

The expected return value is SMDIM_SAMPLEHEADER. If an error occured, other possible return values are:
SMDIE_OUTOFRANGE
SMDIE_NOSAMPLE

4.3.15. SMDI_GetFileSampleHeader

Description

The SMDI_GetFileSampleHeader function does the same as the SMDI_SampleHeaderRequest function, but retrieves the sample information from a file on a local disk.

Definition

DWORD SMDI_GetFileSampleHeader ( char cFileName[MAX_PATH], SMDI_SampleHeader * lpSampleHeader );

Parameters

cFileName
Specifies the file from which the desired sample information is extracted.
lpSampleHeader
A pointer to a SMDI_SampleHeader structure which will be filled with the information.

Return Values

An expected return value is any of the file type constants which indicates with what file format you're dealing. Otherwise, any of the file error constants is returned. Therefore, currently possible return values are:
FT_WAV
FE_OPENERROR
FE_UNKNOWNFORMAT

4.3.16. SMDI_DeleteSample

Description

The SMDI_DeleteSample function deletes a sample from the sampler's memory.

Definition

DWORD SMDI_DeleteSample ( BYTE HA_ID, BYTE SCSI_ID, DWORD dwSampleNumber );

Parameters

HA_ID
The host adapter number to which the device is attached.
SCSI_ID
The device's SCSI ID.
dwSampleNumber
The memory location in the sampler where the sample to be deleted is.

Remarks

Since my sampler does not support sample deletion via SMDI, I can't tell what return values are possible at all.