/* Highlevel functions to access and/or modify EBS files Copyright (C) 1993/94 Ralf Schamburger, Institut fuer Physiologie und Biokybernetik (IPB), Universitaet Erlangen, Deutschland Permission to use, copy, modify, distribute, and sell this software and its documentation for any purpose is hereby granted without fee, provided that the above copyright notice appear in all copies and related publications and that both that copyright notice and this permission notice appear in supporting documentation. The authors make no representations about the suitability of this software for any purpose. It is provided "as is" without express or implied warranty. Send your comments, suggestions or bug reports to ftpebs@uni-erlangen.de Or mail to Institut fuer Physiologie und Biokybernetik Markus Prosch Universitaetsstrasse 17 D-91054 Erlangen Germany $Id: ebshead.h,v 1.16 1994/10/24 18:37:39 msprosch Exp $ */ #ifndef __ebshead_h #define __ebshead_h /* if verbose is defined then if an error occurs ebshead will write it to standard error */ #define EBS_VERBOSE #include "ebs.h" #include #include #include /** EBS_ERROR_LIST **/ #define EBS_NO_ERROR 0 #define EBS_NO_MEMORY 1 #define EBS_NOT_AFILE 2 #define EBS_HEADER_CORRUPT 3 #define EBS_UNEXP_EOF 4 #define EBS_DATABLK_OFFSET_WRONG 5 #define EBS_FIXED_HEADER_RDONLY 6 #define EBS_NO_MORE_TAG 7 #define EBS_NO_TAG_NUMBER 8 #define EBS_64BIT_NOT_SUPPORTED 9 #define EBS_FILE_NOT_ACTIVE 10 #define EBS_FILE_RDONLY 11 #define EBS_FLUSH_FIRST 12 #define EBS_DATABLK_WRONG_END_POS 13 #define EBS_FIXED_HEADER_NOT_SET 14 #define EBS_ONLY_ON_NEW_FILES 15 #define EBS_DATABLK_POS_WRONG 16 #define EBS_CANT_FLUSH 17 #define EBS_CANT_WRITE_VARH 18 #define EBS_ENCODING_ID_NOT_SET 19 /* end of ebs_error_list */ /* macros */ /* Returns the beginning of the data block in the ebs file in ftell format */ #define ebs_data_offset(file) ((file)->data_block) /* pos off data block */ /* error types: no error io errer from system (no memory, file not found,...) ebs error , something was tried what causes an header-data_block conflict. */ typedef enum ebs_error_types {ebs_no_error, ebs_io_error, ebs_error} ebs_error_types; /* the structure in which you should organize the fixed header in your program. remark: donīt manipulate datalength it will be set correctly by ebshead if you follow the short instruction to ebshead. manipulate datalength could cause data lost and errorīs in the header structure. */ typedef struct ebs_fixedheader { unsigned long magic1; unsigned long magic2; unsigned long encoding_id; unsigned long channels; unsigned long sampleshigh; unsigned long sampleslow; unsigned long datalengthhigh; unsigned long datalengthlow; } ebs_fixedheader; /* for internal use of ebshead only */ typedef struct ebs_tagpointer { unsigned long tag; /* tag number */ unsigned long discpos; /* position in ebs file */ unsigned long disclength; /* length of data in tag */ void *mempos; /* position in memory */ unsigned long memlength; /* length of data in memory */ int changeflag; /* 0 unchanged - 1 changed */ } ebs_tagentry; /* for internal use of ebshead only */ typedef struct EBS_FILE { FILE *fd; /* file deskriptor */ int mode; /* rdonly, writenew, read and write */ unsigned long data_block; /* begin of data block */ ebs_tagentry *base; /* tag-base */ unsigned long momtagpos; /* momentary position in tag list */ unsigned long eovarheader; /* end of variable header */ int num; /* number of tags */ int cnt; /* number of remainig tags in buffer */ ebs_fixedheader fixedheader; /* fixedheader */ int fixed_flag; /* 0 does not exist / 1 readonly / 2 read & write */ int flush_flag; /* 0 not flushed / 1 already flushed */ /* this is only for the writing of ebs files important */ ebs_error_types error_type; /* what kind of error io or ebs */ int ebs_errno; /* error number */ } EBS_FILE; /* open a ebs file and returns a ebs file handle for all the other ebs function's. open modes are: 'r' open for reading 'w' creates a new ebs file 'm' open for modify */ EBS_FILE *ebs_open(char *name, char mode); /* close a ebs file and gives all the memory free which was used by that file. remark: don't close the file by your own if you get the stream from ebs_stream because that will cause data lost in the header structure. */ int ebs_close(EBS_FILE *fd); /* that will test if a file is a ebs file and sets the fixedheader if so. returns 0 for false if it is no a ebs file returns 1 for true if it is a ebs file */ int ebs_isebs(char *name, ebs_fixedheader *fh); /* this function returns the position of the given attribute tag on the hard disc. so you can jump to it with fseek. */ unsigned long ebs_getdiscattr(EBS_FILE *fd, unsigned long tag, unsigned long *length); /* you give a ebs file handle, a tag and a variable for length and you will get back a pointer of void, if there is a attribute with that tagnumber else you will get back NULL. remark: the memory to which the pointer belongs is managed by ebshead and could used for other purpose after next call of a ebshead function. if you want to hold it use memcpy. */ void *ebs_getattr(EBS_FILE *fd,uint32 tag, uint32 *length); /* put an attribute with tag and length to a ebs file, if there is still a attribute with that tag, then it will be lost. remark: the attribute entry from the memory which belongs to memptr is copied with memcpy to a different memory location. so you can use the memory after call for other purpose. */ int ebs_putattr(EBS_FILE *pointer,uint32 tag, void *memptr, uint32 length); /* reserves a part of memory to which you can write your appandage of length to the attribute with that tag you gave. if there isn't a attribute with that tag yet, a new one will be created. */ void *ebs_appattr(EBS_FILE *fd, unsigned long tag, unsigned long length); /* deletes a attribute in variable header if it is there, else nothing happens. */ int ebs_clearattr(EBS_FILE *fd,uint32 tag); /* returns the length of an attribute with the number tag. returns max unsigned long if a attribute with that tag does not exist */ unsigned long ebs_taglength(EBS_FILE *pointer, unsigned long tag); /* sets the pointer for ebs_get_tag to first position in header structure */ void ebs_tag_rewind(EBS_FILE *pointer); /* returns the next tag in the ebs variable header structure. if there is no next tag, then it will be returned EBS_ILLEGAL_TAG. */ unsigned long ebs_get_tag(EBS_FILE *pointer); /* writes a copy of the fixed header to fh */ void ebs_getfixedheader(EBS_FILE *fd, ebs_fixedheader *fh); /* takes a copy of fhd as fixed header */ int ebs_putfixedheader(EBS_FILE *pointer,ebs_fixedheader *fhd); /* copies the complete fixed and variabe header structure from ebs file source to target. remark: this is only allowed, if target is open in 'w' mode because all header entries of target will be lost. */ int ebs_copyheader(EBS_FILE *target, EBS_FILE *source); /* sets the file pointer of the ebs file to the start of the data block */ int ebs_rewind(EBS_FILE *pointer); /* returns the file pointer to the ebs file in fopen format. it could happen that you get back a NULL pointer because of the ebs file is written new and the header structure should first written and flushed before the data block is written. */ FILE *ebs_stream(EBS_FILE *fd); /* tells ebs head that now the end of data block is reached. this function is very important because if you write your data to your ebs file and forget to tell ebs head that you finished writting and call ebs_close without calling ebs_setendof_data_block all your data you have written will be lost! */ int ebs_setendof_data_block(EBS_FILE *fd); /* writes changes in header structure to disc. this function will be also used internal of ebs head, so it could be that the changes of the header is written before you call ebs_flush. ebs_close also calls ebs_flush. */ int ebs_flush(EBS_FILE *pointer); /* adds a second variable header to an ebs file, if there is already one nothing will happen */ void ebs_mak2varheader(EBS_FILE *fd); /* clears an error for a ebs file. */ void ebs_clearerr(EBS_FILE *fd); /* returns a pointer to a text string of the last error that happend. */ char *ebs_error_str(EBS_FILE *fd); /* returns the error number of the last error. it could be a number which is set by system or by ebshead. to determine from whom the number is, use ebs_get_error_type */ int ebs_get_error_num(EBS_FILE *fd); /* returns the error type of the last error happend. error types are: no error io error (from system) ebs error */ ebs_error_types ebs_get_error_type(EBS_FILE *fd); #endif /* __ebshead_h */