Assignment 1 Module 1: Primary functions Solution

This is Module 1 of Assignment 1. Module 2 will be much smaller, and will deal specifically with error values and error handling. It will be released after September 17. Module 2 may also contain additional submission details.













Description





In this assignment, you will implement a library to parse vCard files. The link to the format description was posted in the Assignment 1 description several days go. Make sure you understand the format before doing the assignment.




According to the specification (RFC 6350), a vCard object contains:




one specific required property that must appear at least once
multiple optional properties, which may contain parameters



Our Assignment 1 parser will assume a somewhat simpler vCard file:




You can always assume that the parameters of a property (if any) will NOT contain the ":" character. In other words, you can rely on having the ":" character separate the value(s) of a property from everything else



This structure is represented by the Card type in VCardParser.h




According to the specification (RFC 6350), a property component contains:




1 or more values
0 or more parameters



These elements are represented by the Property and Parameter types in VCardParser.h. Property values are strings.




The header also contains a type for representing the date-time property, a few headers, and a couple of other helpful definitions.




Your assignment will be graded using an automated test suite, so you must follow all requirements exactly, or you will lose marks - and possibly get a zero on the assignment.




Required Functions





Read the comments in VCardParser.h carefully. They provide additional implementation details. You must implement every function in VCardParser.h; they are also listed below. If you cannot complete any of the functions, you must provide a stub for every one them.




Applications using the parser library will include VCardParser.h in their main program. The VCardParser.h header has been provided for you. Do not change it in any way. VCardParser.h is the public “face” of our card API. All the helper functions are internal implementation details, and should not be publicly/globally visible. When we grade your code, we will use the standard VCardParser.h to compile and run it.










If you create additional header files, include them in the .c files that use them.































Card parser functions




VCardErrorCode createCard(char* fileName, Card** obj);




This function does the parsing and allocates a Card object. It accepts a filename and an address of a Card pointer (i.e. a double pointer). If the file has been parsed successfully, the card object is allocated and the information is stored in




it. The function then returns OK if the file is successfully parsed and the Card object is created. 
 





However, the parsing can fail for various reasons. In that case, the obj argument is set to NULL and createCard returns a variety of error codes to indicate this.




What VCardErrorCode value should be returned in what situation will be discussed in Module 2. For now, you can return OK if the file is successfully parsed, and IN_FILE otherwise.





Regarding file extensions - both .vcf and .vcard are stated in the specification, so both must be accepted by the parser.




All other file extensions must not.








char* printCard(const Card* obj);




This function returns a humanly readable string representation of the entire card object. Sample output will be added to the assignment description. It must not modify the card object in any way. The function must allocate the string dynamically.





void deleteCard(Card* obj);




This function deallocates the Card object - i.e. frees all memory associated with it - including all of its subcomponents.







const char* printError(VCardErrorCode err);




This function returns a string based on the VCardErrorCode value to make the output of your program easier to understand - i.e. “OK” if err is OK, “INV_FILE” or “invalid file” is INV_FILE was passed, etc.. The function must




allocate the string dynamically. For now, you can return OK if the file is successfully parsed, and IN_FILE otherwise; additional details will be provided in Module 2.




Helper functions




In addition the above functions, you must also write a number of helper functions. We will need to store the types Property, Value, and Parameter in a list. We will also need to print and delete DateTime values, and may need to compare them in future assignments:





void deleteProperty(void* toBeDeleted);




int compareProperties(const void* first, const void* second); char* printProperty(void* toBePrinted);




void deleteParameter(void* toBeDeleted);




int compareParameters(const void* first, const void* second); char* printParameter(void* toBePrinted);




void deleteValue(void* toBeDeleted);




int compareValues(const void* first, const void* second); char* printValue(void* toBePrinted);
















!2
void deleteDate(void* toBeDeleted);




int compareDates(const void* first, const void* second); - this function can be a stub for now, e.g. always return 0. We will flesh it out later, when we need it.




char* printDate(void* toBePrinted);







Additional guidelines and requirements




In addition, it is strongly recommended that you write additional helpers functions for parsing the file - e.g. parsing a property, parameter, or a date-time. You should also write delete...() functions for all the structs, since they will all be dynamically allocated.




All required functions must be in a file called VCardParser.c. You are free to create your additional "helper functions" in a separate .c file, if you find some recurring processing steps that you would like to factor out into a single place. Do not place headers for these additional helper function in VCardParser.h. They must be in a separate header file, since they are internal to your implementation and not for public users of the utility package.




For your own test purposes, you will also want to code a main program in another .c file that calls your functions with a variety of test cases, but you won't submit that program. Do not put your main() function in VCardParser.c, or else the test program will fail due to multiple definitions of main(); you will lose marks for that, and may get a zero for the assignment.




Your functions are supposed to be robust. They will be tested with various kinds of invalid data and must detect problems without crashing. If your functions encounter a problem, they must free all memory and return.




Recommended development path:





Start by implementing a simple parser that extracts the FN property
Add handling of multiple optional properties with single values



Add handling of properties with compound values



Add line unfolding. Line unfolding is part of the format specification and you must implement it to receive full marks.



Add handling of properties with parameters



Add deleteCard functionality



Test for memory leaks



Add printCard functionality



Test for memory leaks



Implement proper error code returns (Module 2)



Add printError functionality



Test for memory leaks







Important points 





Do:




Do be careful about upper/lower case.
Do include comments with your name and student ID at the top of every file you submit




Do not:




Do not submit VCardParser.h or LinkedListAPI.h. If they are submitted, they will be overwritten.
Do not change the given typedefs or function prototypes VCardParser.h
Do not hardcode any paths or directory information into #include statements, e.g.

#include "../include/SomeHeader.h




Do not submit any main() functions
Do not exit the program from one of the parser functions if a problem is encountered, return an error value instead.
Do not print anything to the command line.
Do not assume that your pointers are valid. Always check for NULL pointers in function arguments.
3!

Failure to follow any of the above points may result in loss of marks, or even a zero for the assignment if they cause compiler errors with the test harness.




Submission structure




The submission must have the following directory structure:




assign1/ - contains the Makefile and README file. The README file will be discussed in Module 2.




assign1/bin - should be empty, but this is where the Makefile will place the shared lib files.

assign1/src - contains VCardParser.c , LinkedListAPI.c, and your additional source files.

assign1/include - contains your additional headers. Do not submit VCardParser.h and

LinkedListAPI.h.




Makefile




You will need to provide a Makefile with the following functionality:




make list creates a static library libllist.a in assign1/bin
make parser creates a static library libcparse.a in assign1/bin
make or make all creates libllist.a and libcparse.a in assign1/bin
make clean removes all .o and .a files



Evaluation




Your code must compile, run, and have all of the specified functionality implemented. Any compiler errors will result in the automatic grade of zero for the assignment.




Marks will be deducted for:




Incorrect and missing functionality
Deviations from the requirements
Run-time errors
Compiler warnings
Memory leaks
Failure to follow submission instructions



Submission




Submit your files as a Zip archive using Moodle. File name must be be A1FirstnameLastname.zip. 
 Late submissions: see course outline for late submission policies.




This assignment is individual work and is subject to the University Academic Misconduct Policy. See course outline for details)














































!4