~ubuntu-branches/ubuntu/oneiric/e00compr/oneiric : revision 1

1

E00compr 1.0

2

3

Compressed E00 Read/Write Library

4

5

By Daniel Morissette, dmorissette@dmsolutions.ca

6

--------------------------------------

7

The latest version of this documentation and of the whole package can be

8

obtained from http://avce00.maptools.org/

9

--------------------------------------

10

11

Table of Contents

12

13

* Copyright and License terms

14

* What is E00compr?

15

* Building the package

16

* Using the 'e00conv' Conversion program

17

* How to use the library in your programs

18

* Library functions to Read compressed E00 files

19

o Example

20

o E00ReadPtr data type

21

o E00ReadOpen()

22

o E00ReadCallbackOpen()

23

o E00ReadClose()

24

o E00ReadNextLine()

25

o E00ReadRewind()

26

* Library functions to Write compressed E00 files

27

o Example

28

o E00WritePtr data type

29

o E00WriteOpen()

30

o E00WriteCallbackOpen()

31

o E00WriteClose()

32

o E00WriteNextLine()

33

* Trapping errors reported by the library

34

o CPLSetErrorHandler()

35

o CPLError()

36

o CPLGetLastErrorNo()

37

o CPLGetLastErrorMsg()

38

o Errors generated by the library and their meaning

39

40

Copyright and License terms

41

42

The most part of the E00COMPR library is

43

44

it also contains portions (CPL lib) that are

45

46

47

The AVCE00 library and the supporting CPL code are freely available under

48

the following Open Source license terms:

49

50

51

52

53

Permission is hereby granted, free of charge, to any person obtaining a

54

copy of this software and associated documentation files (the

55

"Software"), to deal in the Software without restriction, including

56

without limitation the rights to use, copy, modify, merge, publish,

57

distribute, sublicense, and/or sell copies of the Software, and to

58

permit persons to whom the Software is furnished to do so, subject to

59

the following conditions:

60

61

The above copyright notice and this permission notice shall be included

62

in all copies or substantial portions of the Software.

63

64

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS

65

OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF

66

MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.

67

IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY

68

CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,

69

TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE

70

SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

71

72

73

What is E00compr?

74

75

E00compr is an ANSI C library that reads and writes Arc/Info compressed E00

76

files. Both "PARTIAL" and "FULL" compression levels are supported.

77

78

This package can be divided in three parts:

79

80

* The 'e00conv' command-line program. This program takes a E00 file as

81

input (compressed or not) and copies it to a new file with the

82

requested compression level (NONE, PARTIAL or FULL).

83

84

* A set of library functions to read compressed E00 files. These

85

functions read a E00 file (compressed or not) and return a stream of

86

uncompressed lines, making the E00 file appear as if it was not

87

compressed.

88

89

* A set of library functions to write compressed E00 files. These

90

functions take one line after another from what should be a

91

uncompressed E00 file, and write them to a file with the requested

92

compression level, either NONE, PARTIAL or FULL.

93

94

Building the package

95

96

The library has already been succesfully built on Windows (with MSVC++ 4

97

and 5), and on Linux (with gcc).

98

99

Windows users:

100

101

A MSVC++ 4 makefile (e00compr.mak) to build the 'e00conv.exe'

102

command-line program is included with the distribution. You should

103

have no problem opening this file with MSVC++ and building the package

104

directly.

105

106

MSVC++ 5 will ask you if you want to convert the makefile to the new

107

project format. Answer "Yes" and you should be just fine.

108

109

If you are using another development environment, then you will likley

110

need to build your own project. Include the following files in your

111

project:

112

113

e00compr.h

114

e00read.c

115

e00write.c

116

117

cpl_port.h

118

cpl_conv.h

119

cpl_error.h

120

cpl_vsi.h

121

cpl_conv.c

122

cpl_error.c

123

cpl_vsisimple.c

124

125

Unix users:

126

127

A Makefile is included with the distribution. Its default target will

128

build the 'e00conv' executable using gcc. Take a look at the

129

definitions at the top of the Makefile to see if you need to modify it

130

to build in your own environment.

131

132

In most cases, building the package should be as simple as extracting

133

the distribution files to a empty directory, and then going to this

134

directory and typing make.

135

136

If you encounter problems with the Makefile, then make sure that it

137

contains Unix line breaks. The line breaks are sometimes altered when

138

the distribution is copied between PCs and Unix systems, and Make

139

doesn't seem to like Makefiles that contain DOS CR-LF line breaks.

140

141

Using the 'e00conv' Conversion Program

142

143

'e00conv' is a command-line executable that takes a E00 file as input

144

(compressed or not) and copies it to a new file with the requested

145

compression level (NONE, PARTIAL or FULL).

146

147

e00conv <input_file> <output_file> [NONE|PARTIAL|FULL]

148

149

o input_file is the name of the E00 file to read from.

150

151

o output_file is the name of the file to create. If the file

152

already exists then it is overwritten.

153

154

o The last argument is optional and specifies the compression level

155

to use when creating the output file (one of NONE, PARTIAL or

156

FULL). The default is NONE (uncompressed).

157

158

How to use the library in your programs

159

160

--------------------------------------

161

Note: If you are not planning to use the library in your programs,

162

then you can stop reading here...

163

the rest of this document won't be of any use to you!

164

--------------------------------------

165

166

To use the library in your programs, include the file "e00compr.h", and

167

link with the "e00compr.a" library produced by the Unix Makefile.

168

169

If you are working in a Windows development environment (i.e. with

170

projects, no Makefiles!) then add all the C files from the distribution to

171

your project, except "e00conv.c".

172

173

Library functions to Read compressed E00 files

174

175

All the read functions are defined inside "e00read.c". Information about

176

the file currently being read is stored inside an internal structure. You

177

do not need to understand the contents of this structure to use the

178

library.

179

180

All you need is to declare a E00ReadPtr variable which will serve as a

181

handle on the input file for all the other functions.

182

183

You use the following functions to read a E00 file:

184

185

E00ReadPtr E00ReadOpen(const char *pszFname);

186

void E00ReadClose(E00ReadPtr hInfo);

187

188

const char *E00ReadNextLine(E00ReadPtr hInfo);

189

void E00ReadRewind(E00ReadPtr hInfo);

190

191

Each function is described after the example below.

192

193

Example:

194

195

This short example uses the library to read a E00 compressed file

196

("test.e00") and prints the uncompressed result to stdout.

197

198

/**********************************************************************

199

* ex_read.c

200

*

201

* This example program illustrates the use of the E00ReadOpen()

202

* and associated compressed E00 read functions.

203

**********************************************************************/

204

205

#include <stdio.h>

206

207

#include "e00compr.h"

208

209

int main(int argc, char *argv[])

210

{

211

E00ReadPtr hReadPtr;

212

const char *pszLine;

213

214

/* Open input */

215

hReadPtr = E00ReadOpen("test.e00");

216

217

if (hReadPtr)

218

{

219

/* Read lines from input until we reach EOF */

220

while((pszLine = E00ReadNextLine(hReadPtr)) != NULL)

221

{

222

if (CPLGetLastErrorNo() == 0)

223

printf("%s\n", pszLine);

224

else

225

{

226

/* An error happened while reading the last line... */

227

break;

228

}

229

}

230

231

/* Close input file */

232

E00ReadClose(hReadPtr);

233

}

234

else

235

{

236

/* ERROR ... failed to open input file */

237

}

238

239

return 0;

240

}

241

242

243

E00ReadPtr data type

244

245

A variable of type E00ReadPtr serves as a handle on the current input

246

file.

247

248

The handle is allocated by E00ReadOpen(), and you must call

249

E00ReadClose() to properly release the memory associated with it.

250

251

E00ReadOpen()

252

253

E00ReadPtr E00ReadOpen(const char *pszFname);

254

255

Opens a E00 input file and returns a E00ReadPtr handle.

256

257

The input file can be in compressed or uncompressed format.

258

E00ReadClose() will eventually have to be called to release the

259

returned handle.

260

261

Returns NULL if the file could not be opened or if it does not appear

262

to be a valid E00 file.

263

264

E00ReadCallbackOpen()

265

266

E00ReadPtr E00ReadCallbackOpen(void *pRefData,

267

const char * (*pfnReadNextLine)(void *),

268

void (*pfnReadRewind)(void *));

269

270

This is an alternative to E00ReadOpen() for cases where you have to do

271

all the file management yourself. You open/close the file yourself and

272

provide 2 callback functions: to read from the file and rewind the

273

file pointer.

274

275

pRefData is your own handle on the physical file and can be whatever

276

you want... it is not used by the library, it will be passed directly

277

to your 2 callback functions when they are called.

278

279

The callback functions must have the following C prototype:

280

281

const char *myReadNextLine(void *pRefData);

282

void myReadRewind(void *pRefData);

283

284

285

myReadNextLine() should return a reference to its own internal

286

buffer, or NULL if an error happens or when EOF is reached.

287

288

E00ReadCallbackOpen() returns a E00ReadPtr handle or NULL if the file

289

does not appear to be a valid E00 file.

290

291

For an example of the use of this method, see the file ex_readcb.c

292

included in the library distribution.

293

294

E00ReadClose()

295

296

void E00ReadClose(E00ReadPtr hInfo);

297

298

Closes the physical file and releases any memory associated with a

299

E00ReadPtr handle.

300

301

E00ReadNextLine()

302

303

const char *E00ReadNextLine(E00ReadPtr hInfo);

304

305

Returns the next line of input from the E00 file in uncompressed form

306

or NULL if we reached EOF or if an error happened. The returned line

307

is a null-terminated string, and it does not include a newline

308

character. Call CPLGetLastErrorNo() after calling E00ReadNextLine() to

309

make sure that the whole line was read succesfully.

310

311

Note that E00ReadNextLine() returns a reference to an internal buffer

312

whose contents will be valid only until the next call to this

313

function. The caller should not attempt to free() the returned

314

pointer.

315

316

E00ReadRewind()

317

318

void E00ReadRewind(E00ReadPtr hInfo);

319

320

Rewinds the E00ReadPtr just like the stdio rewind() function would do.

321

322

Useful when you have to do multiple read passes on the same input

323

file.

324

325

Library functions to Write compressed E00 files

326

327

The write functions are defined inside "e00write.c". The information about

328

the file currently being written is stored inside an internal structure. As

329

for the read library, you do not need to understand the contents of this

330

structure to use the library.

331

332

Your program has to declare a E00WritePtr variable which will serve as a

333

handle on the output file for all the other functions.

334

335

You use the following functions to write a E00 file:

336

337

E00WritePtr E00WriteOpen(const char *pszFname, int nComprLevel);

338

void E00WriteClose(E00WritePtr hInfo);

339

340

int E00WriteNextLine(E00WritePtr hInfo, const char *pszLine);

341

342

Each function is described after the example below.

343

344

Example:

345

346

This example is a simpler version of the "e00conv.c" program that is

347

included with this distribution. It uses the read library to read a

348

E00 file ("test1.e00") and uses the write library to copy its contents

349

one line at a time to a new E00 file ("test2.e00") with FULL

350

compression:

351

352

/**********************************************************************

353

* ex_write.c

354

*

355

* This example program illustrates the use of the E00WriteOpen()

356

* and associated compressed E00 write functions.

357

**********************************************************************/

358

#include <stdio.h>

359

360

#include "e00compr.h"

361

362

int main(int argc, char *argv[])

363

{

364

E00ReadPtr hReadPtr;

365

E00WritePtr hWritePtr;

366

const char *pszLine;

367

int nStatus = 0;

368

369

/* Open input file */

370

hReadPtr = E00ReadOpen("test1.e00");

371

372

if (hReadPtr)

373

{

374

/* Open output file */

375

hWritePtr = E00WriteOpen("test2.e00", E00_COMPR_FULL);

376

377

if (hWritePtr)

378

{

379

/* Read lines from input until we reach EOF */

380

while((pszLine = E00ReadNextLine(hReadPtr)) != NULL)

381

{

382

if ((nStatus = CPLGetLastErrorNo()) == 0)

383

nStatus = E00WriteNextLine(hWritePtr, pszLine);

384

385

if (nStatus != 0)

386

{

387

/* An error happened while converting the last

388

* line... abort*/

389

break;

390

}

391

}

392

/* Close output file. */

393

E00WriteClose(hWritePtr);

394

}

395

else

396

{

397

/* ERROR ... failed to open output file */

398

nStatus = CPLGetLastErrorNo();

399

}

400

401

/* Close input file. */

402

E00ReadClose(hReadPtr);

403

}

404

else

405

{

406

/* ERROR ... failed to open input file */

407

nStatus = CPLGetLastErrorNo();

408

}

409

410

return nStatus;

411

}

412

413

E00WritePtr data type

414

415

A variable of type E00WritePtr serves as a handle on the current input

416

file.

417

418

The handle is allocated by E00WriteOpen(), and you must call

419

E00WriteClose() to properly release the memory associated with it.

420

421

E00WriteOpen()

422

423

E00WritePtr E00WriteOpen(const char *pszFname, int nComprLevel);

424

425

Creates a new E00 file for output with the specified compression

426

level, and returns a E00WritePtr handle for it. If the file already

427

exists, then it is overwritten.

428

429

nComprLevel is one of Arc/Info's 3 levels of compression:

430

431

o E00_COMPR_NONE - creates an uncompressed file.

432

o E00_COMPR_PARTIAL - creates a file with PARTIAL compression.

433

o E00_COMPR_FULL - creates a file with FULL compression.

434

435

Returns NULL if the file could not be opened.

436

437

E00WriteCallbackOpen()

438

439

E00WritePtr E00WriteCallbackOpen(void *pRefData,

440

int (*pfnWriteNextLine)(void *, const char *),

441

int nComprLevel);

442

443

This is an alternative to E00WriteOpen() for cases where you have to

444

do all the file management yourself. You open/close the file yourself

445

and provide a callback function to write one line at a time to the

446

file.

447

448

pRefData is your own handle on the physical file and can be whatever

449

you want... it is not used by the library, it will be passed directly

450

to your callback function when it is called.

451

452

The callback function must have the following C prototype:

453

454

int myWriteNextLine(void *pRefData, const char *pszLine);

455

456

myWriteNextLine() should return a positive value on success (the

457

number of chars written, like printf() does) or -1 if an error

458

happened.

459

460

The value passed by the library in pszLine is not terminated by a

461

'\n' character... it is assumed that your myWriteNextLine()

462

implementation will take care of terminating the line with a '\n'

463

if necessary.

464

465

nComprLevel is one of Arc/Info's 3 levels of compression:

466

467

o E00_COMPR_NONE - creates an uncompressed file.

468

o E00_COMPR_PARTIAL - creates a file with PARTIAL compression.

469

o E00_COMPR_FULL - creates a file with FULL compression.

470

471

E00WriteCallbackOpen() returns a new E00ReadWritePtr handle and

472

E00WriteClose() will eventually have to be called to release the

473

resources used by the new handle.

474

475

For an example of the use of this method, see the file ex_writecb.c

476

included in the library distribution.

477

478

E00WriteClose()

479

480

void E00WriteClose(E00WritePtr hInfo);

481

482

Closes the physical file and release any memory associated with a

483

E00WritePtr handle.

484

485

E00WriteNextLine()

486

487

int E00WriteNextLine(E00WritePtr hInfo, const char *pszLine);

488

489

Takes the next line of what should be headed to a uncompressed E00

490

file, converts it to the requested compression level, and writes the

491

(compressed) result to the output file.

492

493

pszLine should be a null-terminated string with a maximum of 80

494

characters (E00 lines cannot be longer than 80 characters). Do NOT

495

include a '\n' at the end of the line, it will be added automatically

496

by the function if it is needed.

497

498

Returns 0 if the line was processed succesfully, or an error number

499

(see error codes below) if an error happened.

500

501

Note that this function does not do any syntax check on the input you

502

provide. It assumes that what you pass to it is a valid stream of E00

503

lines as they would appear in an uncompressed E00 file.

504

505

Trapping errors reported by the library

506

507

When errors happen, the library's default behavior is to report an error

508

message on stderr, and to fail nicely, usually by simulating a EOF

509

situation. Errors are reported through the function CPLError() defined in

510

"cpl_error.c".

511

512

While this is sufficient for the purposes of the 'e00conv' command-line

513

program, you may want to trap and handle errors yourself if you use the

514

library in a bigger application (a GUI application for instance).

515

516

CPLSetErrorHandler()

517

518

void CPLSetErrorHandler(void (*pfnErrorHandler)(CPLErr, int, const char *));

519

520

You can use CPLSetErrorHandler() to override the default error handler

521

function. Your new error handler should be a C function with the

522

following prototype:

523

524

void MyErrorHandler(CPLErr eErrClass, int err_no, const char *msg);

525

526

And you register it with the following call at the beginning of your

527

program:

528

529

CPLSetErrorHandler( MyErrorHandler );

530

531

CPLError()

532

533

void CPLError(CPLErr eErrClass, int err_no, const char *fmt, ...);

534

535

The library reports errors through this function. It's default

536

behavior is to display the error messages to stderr, but it can be

537

overridden using CPLSetErrorHandler().

538

539

You can call CPLGetLastErrorNo() or CPLGetLastErrorMsg() to get the

540

last error number and string.

541

542

eErrClass defines the severity of the error:

543

544

typedef enum

545

{

546

CE_None = 0,

547

CE_Log = 1,

548

CE_Warning = 2,

549

CE_Failure = 3,

550

CE_Fatal = 4

551

} CPLErr;

552

553

Error class CE_Fatal will abort the execution of the program, it is

554

mainly used for out of memory errors, or unrecoverable situations of

555

that kind. All the other error classes return control to the calling

556

function.

557

558

CPLGetLastErrorNo()

559

560

int CPLGetLastErrorNo();

561

562

Returns the number of the last error that was produced. Returns 0 if

563

the last library function that was called completed without any error.

564

See the list of possible error numbers below.

565

566

Note: This function works even if you redefined your own error handler

567

using CPLSetErrorHandler() .

568

569

CPLGetLastErrorMsg()

570

571

const char *CPLGetLastErrorMsg();

572

573

Returns a reference to a static buffer containing the last error

574

message that was produced. The caller should not attempt to free this

575

buffer. Returns an empty string ("") if the last library function that

576

was called completed without any error.

577

578

Note: This function works even if you redefined your own error handler

579

using CPLSetErrorHandler() .

580

581

Errors generated by the library and their meaning:

582

583

The values for the error codes returned by the library are defined in the

584

file cpl_error.h.

585

586

#define CPLE_OutOfMemory 2

587

#define CPLE_FileIO 3

588

#define CPLE_OpenFailed 4

589

#define CPLE_IllegalArg 5

590

#define CPLE_NotSupported 6

591

#define CPLE_AssertionFailed 7

592

593

The following errors codes can be returned:

594

595

Error Code Description

596

0 Success, no error.

597

CPLE_OutOfMemory Memory allocation failed. This is a fatal

598

error, it will abort the program execution.

599

There is currently no proper way to recover

600

from it.

601

CPLE_FileIO Unexpected error reading or writing to a

602

file. This can also happen if an input file

603

is corrupt.

604

CPLE_OpenFailed Failed to open the input ou output file.

605

Check for permissions, disk space, etc.

606

CPLE_IllegalArg Illegal argument passed to one of the

607

CPLE_AssertionFailed library's functions. This is a kind of

608

internal error that should not happen unless

609

the lib is modified or is not used as it is

610

expected.

611

CPLE_NotSupported One of the functions encountered an

612

unsupported/unexpected case in one of the

613

files. This error can also be a sign that the

614

file is corrupt.

615

616

------------------------------------------------------------------------

617

Last Update: $Date: 2005/09/17 14:50:29 $

618

Daniel Morissette, dmorissette@dmsolutions.ca