Writing an API to communicate with a device connected on Serial port

Question

I am afraid that several terminologies in my question are wrong. Please bear with me and correct me wherever I am wrong.

I have to write a library/program that will provide set of function to operate a card reader attached at Serial Port. Like to eject card that was inserted in it, user will simply have to call in his code, for example,

cardEject(); // or
track2Data( response); // to read data of track 2 of magnetic stripe.

cardEject() and other functions will themselves take care of opening serial port, writing data to it, checking the acknowledgement, checking error code, resending command in case of failure, etc. I am pretty clear about communicating with devices on serial port.

My question is, after writing all these functions and testing them, how should I provide them to the user.
Should I give him a header file (.h) and an object file (.o)? So that he can link to the object while compiling his actual program.
Should I provide a static library (.a)?

Which one is a better idea?

Is it a good idea that each function open serial port and then close it? Or a initCardReader() opens it, sets its properties and closeCardReader() should close it? All other functions can only be called after initCardReader()?

Now a silly but real question :-) what is the terminology used for such programs? Is it a driver or library or device interface? What is the correct label for such projects?

Thanks for your time.

Edit
Thanks to all of you for guiding me. Really appreciated.
This API has to become part of a larger project. In fact, I will be working on that project too. But there is a strong possibility that this API will be used in other projects with or without me. I think, considering the possible use in other projects, library makes more sense. Kindly correct me if I am wrong.

Answer 1

My two cents:

I think how you provide the output depends on the user. Is this person working closely with you in the same company / project, or is this going to an external source?

If its going external definitely make it a library...it may be easier to create a library in the other case as well, since it would mean less things for this other user to worry about.

Is your code going to be integrated into a larger project? If so, you should just build your code into a subfolder in this project and provide him with the required functions that are needed. I think this portion is more subjective than anything.

Regarding opening/closing the ports, again it depends how it will work. If you are simply providing the API for other programmers to use (and don't know how it will work), I would say abstract it into an initCardReader/closeCardReader function call. That way, if the user wants to do multiple transactions he doesn't need to worry about wasting processing time with each call he makes...he can simply open/close at his discretion.

And it sounds to me like you are writing API calls for a card-reader device driver ;)

Answer 2

I think you should do it as simple as possible, a static library and a header file should be a good start.

One way is to treat the card reader in the same way any other resource like a file, meaning you open/init the card reader and return some handle that identifies the card reader. Then subsequently use that in all functions when accessing the card reader.

Answer 3

I'll go with the answer from Anders K. you are writing a API for your card reader.

My two cents about the more general questions:

Your question about open/close connection, there are two aspects that you have to keep in mind. Lets assume you proceed the way in which you leave it up to the user to open and close the connection. What if he forgets to close it after he finished, what when multiple processes access the card-reader? In those scenarios you may want to free the port to the other processes after each write/read. In the end it depends on the operations that will be done, the process using your API will usually always call your read method multiple times you might want to leave it open or you could implement a read multiple records in your API again avoiding the possibility that a connection gets left open.

I would make a library if it is mainly used in other projects. It also puts you into the position of changing the lib at one place for everyone to implement. Again depending on where you will implement it, there are numerous scenarios when adding your code is the better option.

Answer 4

You can put this set of functions in the shared lib (like: libCardReader.so) and give away with the Header file to the programmer to reference and use it in his/her code. The following link provide very good intro about building the SO file (http://www.network-theory.co.uk/docs/gccintro/)