The qDecoder Project

qDecoder Function Reference



Query and Cookie Handling Functions

qDecoder()

Syntax:int qDecoder(void);
Function:COOKIE, GET, POST(multipart/form-data 인코딩 포함) 방식으로 저달된 쿼리를 해석하여 linked-list에 저장
Return:성공시 전달받은 인자의 갯수, 에러시 -1.
Note:쿼리가 해석되는 순서는 (1)COOKIE (2)GET (3)POST 이다. 따라서 같은 이름을 갖는 COOKIE와 GET 변수 그리고 POST 변수가 해석되었을때, qValue("변수명")은 COOKIE의 값을 복귀한다. 이것은 보안적으로 의미가 있는데, 보통 어플리케이션은 검증된 상태정보를 COOKIE에 저장해 놓고 별도의 처리없이 사용을 하기 때문에 GET/POST 방식으로 전달된 동일한 변수명이 qValue()에서 COOKIE보다 먼저 읽혀지는 것을 방지할 필요가 있다.

qDecoder()는 qValue()와 같은 관련 함수가 호출되면 내부적으로 자동 호출되므로 명시적으로 호출을 할 필요는 없다.

multipart/form-data 인코딩을 통해 업로딩된 파일이 있을경우에는, "변수명.length", "변수명.contenttype", "변수명.name"의 변수가 자동으로 삽입된다. "변수명.length"엔 자료의 바이트수가 저장되며, "변수명.contenttype"엔 "image/jpeg"와 같은 컨텐트 타입이 저장되고, "변수명.name"은 사용자가 전송한 파일명이 저장된다. 이때 파일명은 경로를 제외한 순수 파일명만 저장된다. (/"C:Data\/a.gif"일경우 "/a.gif"만이 저장) 또한, 자동으로 생성된 인자(변수명.name, 변수명.length)는 복귀값(인자 갯수)에 반영되지 않는다.
Example:Example 1: application/x-www-form-urlencoded (GET/POST Method) [HTML] <form method="post" action="input.cgi"> User ID <input type="text" name="userID"><br> <input type="submit"> </form> [Parsed Queries] name = "userID" value = "character strings users input" [C] #include <stdio.h> #include "qDecoder.h" void main(void) { char *id; qContentType("text/html"); id = qValue("userID"); printf("%s", id); } Example 2: multipart/form-data [HTML] <form method="post" action="upload.cgi" enctype="multipart/form-data"> User ID <input type="text" name="userID"><br> Attachment <input type="file" name="binary"><br> <input type="submit"> </form> [Parsed Queries] name = "userID" value = "character strings users input" name = "binary" value = "/binary%20data%20of%20/a.gif" name = "binary.length" value = "128" name = "binary.filename" value = "/a.gif" [C] #include <stdio.h> #include <stdlib.h> #include "qDecoder.h" void main(void) { FILE *fp; char *userID; char *filedata, *filename; int filelength, i; qContentType("text/plain"); userID = qValue("userID"); filedata = qValue("binary"); filelength = qiValue("binary.length"); filename = qValue("binary.filename"); fp = fopen(filename, "wb"); for(i = filelength; i > 0; i--) fprintf(fp, "%c", *(filedata++)); fclose(fp); printf("%s : %s(%s bytes) saved.", userID, filename, filelength); }

qValue()

Syntax:char *qValue(char *format, ...);
Function:Linked-list에서 변수명에대한 값(COOKIE, GET, POST)을 찾아 포인터를 넘겨줌
Return:변수명이 존재하면 변수값의 포인터, 변수명이 없으면 NULL.
Note:변수명이 존재하면 변수값의 포인터, 변수명이 없으면 NULL
Note: qValue()는 qDecoder()에 의해 생성된 쿼리 인덱스의 포인터만을 복귀한다. 따라서 qValue로 전달받은 포인터를 free() 하여서는 안된다. 할당 메모리 해제는 qFree() 함수를 통해(일반적으로 프로그램 종료전) 수행하여야 한다.

qDecoder() 함수가 호출되지 않았다면, 자동으로 qDecoder()를 내부 호출한다.
Example:char *test; test = qValue("VARIABLE NAME"); char *test; int i = 1; test = qValue("COUNT.%d", i);

qiValue()

Syntax:int qiValue(char *format, ...);
Function:qValue()와 같으나, 값(숫자 문자열)을 정수로 변환하여 복귀함.
Return:성공시 변수값(숫자 문자열)에 대한 정수값. 변수명이 존재하지 않거나 변환 불가능시 0 .
Example:int test; test = qiValue("VARIABLE NAME"); int test, i = 1; test = qValue("COUNT.%d", i);

qValueDefault()

Syntax:char *qValueDefault(char *defstr, char *format, ...);
Function:쿼리가 없을때 기본 인자를 설정하기 위해 사용하는 qValue()의 간략 함수이다.
Return:qValue()와 같으나 변수가 존재하지 않을시 defstr의 포인터를 복귀.
Example:value = qValueDefault("Seoul", "COUNTRY");

qValueNotEmpty()

Syntax:char *qValueNotEmpty(char *errmsg, char *format, ...);
Function:쿼리가 없거나 공백 문자열("")이 복귀될 시 qError()함수를 사용해 지정된 에러메세지를 출력한다.
Return:NULL에 대한 오류처리가 내장된 것을 제외하곤 qValue()와 같다.
Example:value = qValueNotEmpty("Enter country name", "COUNTRY");

qValueReplace()

Syntax:char *qValueReplace(char *mode, char *name, char *tokstr, char *word);
Function:Linked-list 문자열에 대한 문자열 및 토큰 치환을 한다.
Return:치환된 문자열 포인터.
Note:qValueReplace()는 기본적으로 qStrReplace()의 Wrapping 함수이다. 차이점은 소스 문자열을 쿼리 값(name에 대한 linked-list의 value)으로 한다는 점이며, 그 변환이 linked-list 자체에 직접적으로 가해질 수도 있음에 있다.
따라서 qValueReplace()의 인자 사용법은 qStrReplace()와 기본적으로 동일하다.

'name' 인자는 소스 문자열로 사용할 linked-list의 쿼리명이며 해당 value을 치환시 사용할 소스 문자열로 한다.

'mode' 인자는 "sr"와 같이 두개의 분리된 문자로 구성된 문자열이다.

첫번째 문자는 치환방법을 정의하며 't'나 's'가 위치할 수 있다. 't'는 [t]oken을 의미하며 tokstr 문자열의 각 문자를 토큰으로 소스 문자열 (주어진 name에 대한 linked-list의 value 문자열)을 비교하여, 매칭이 되는 문자를 word 문자열로 치환한다. 's'는 [s]tring을 의미하여 tokstr 스트링 자체를 하나의 토큰으로 하여 소스 스트링내에 나타나는 tokstr 매칭 문자열을 word 문자열로 치환한다.

두번째 문자는 치환된 문자열에 대한 기록 형태를 나타내며 'n'과 'r'이 사용될 수 있다. 'n'은 [n]ew를 나타내며 치환된 결과 문자열을 새로운 메모리 공간에 저장하여 해당 포인터를 리턴하게 한다. 따라서 소스 스트링 linked-list 자체는 원상태가 유지되고 해당 메모리는 사용자 측면에서 free() 되어야 한다. 'r'은 [r]eplace를 의미하며 치환 결과를 linked-list 자체에 덮어 씀을 의미한다. 이것은 내부적으로 메모리 재할당을 통해 이루어 진다.

결과적으로 'mode' 인자는 다음과 같이 4개의 조합 가능한 경우를 갖는다.

 Mode "tn" : [t]oken 치환 & 새로운 공간에 결과를 담아 복귀
 Mode "tr" : [t]oken 치환 & linked-list 자체를 수정
 Mode "sn" : [s]tring 치환 & 새로운 공간에 결과를 담아 복귀
 Mode "sr" : [s]tring 치환 & linked-list 자체를 수정
Example:Example 1) char *retstr, *mode; mode = qValue("mode"); qContentType("text/plain"); printf("before %s : srcstr = %s\n", mode, qValue("srcstr")); retstr = qValueReplace(mode, "srcstr", "hello", "[?]"); printf("after %s : srcstr = %s\n", mode, qValue("srcstr")); printf(" retstr = %s\n\n", retstr); if(mode[1] == 'n') free(retstr); return 0; Result 'tn') before tn : srcstr = hello world after tn : srcstr = hello world retstr = [?][?][?][?][?] w[?]r[?]d Result 'tr') before tr : srcstr = hello world after tr : srcstr = [?][?][?][?][?] w[?]r[?]d retstr = [?][?][?][?][?] w[?]r[?]d Result 'sn') before sn : srcstr = hello world after sn : srcstr = hello world retstr = [?] world Result 'sr') before sr : srcstr = hello world after sr : srcstr = [?] world retstr = [?] world

qGetFirstEntry()

Syntax:Q_Entry *qGetFirstEntry(void);
Function:Linked-list의 첫번째 Q_Entry 포인터를 복귀한다.
Return:Linked-list에 데이터가 있을때엔 Q_Entry 포인터를 복귀. 없을경우엔 NULL
Note:qDecoder()에 의해 사용되는 linked-list를 직접 조작하고자 할때 루트 포인터를 얻기위해 사용한다.
Example:Q_Entry *first; first = qGetFirstEntry();

qValueFirst()

Syntax:char *qValueFirst(char *format, ...);
Function:동일한 변수명을 갖는 인자들을 순차적으로 패치할 때 사용.
Return:성공시 동일한 변수명을 갖는 인자들에 대한 첫번째 변수값 포인터를 복귀, 변수명이 없을시 NULL.
Example:char *list; for(list = qValueFirst("checklist"); list; list = qValueNext()) { printf("checklist = %s<br>\n", list); }

qValueNext()

Syntax:char *qValueNext(void);
Function:qValueFirst()로 찾는 것을 계속한다.
Return:성공시 변수값의 포인터, 더이상의 동일 변수명이 없을때 NULL.
Example:char *list; for(list = qValueFirst("checklist"); list; list = qValueNext()) { printf("checklist = %s<br>\n", list); }

qValueAdd()

Syntax:char *qValueAdd(char *name, char *format, ...);
Function:변수를 linked-list에 강제 추가함.
Return:Linked-list에서의 추가된 name에 대한 문자열 포인터
Note:같은 변수명이 존재할 경우엔 값이 교체된다.
Example:qValueAdd("NAME", "Seung-young Kim"); name = qValue("NAME");

qValueRemove()

Syntax:void qValueRemove(char *format, ...);
Function:Linked-list에서 해당 엔트리를 삭제한다.
Example:qValueRemove("NAME");

qValueType()

Syntax:char qValueType(char *format, ...);
Function:쿼리값의 전달 형태(Cookie, GET, POST)를 복귀한다.
Return:쿠키 `C`, GET 메소드 `G`, POST 메소드 `P`, 새로운 데이터(qValueAdd) `N`, 변수 없음 `-`.
Example:switch(qValueType(name)) { case 'C' : { cookie_cnt++; break; } case 'G' : { get_cnt++; break; } case 'P' : { post_cnt++; break; } case 'N' : { new_cnt++; break; } }

qCookieSet()

Syntax:void qCookieSet(char *name, char *value, int exp_days, char *path, char *domain, char *secure);
Function:name=value 에 해당하는 쿠키를 설정함.
Note:qCookieSet()을 통해 쿠키를 설정했을 경우 특성상 qValue()를 통해 값이 넘겨지는 시점은 다음번 프로그램 호출시가 된다. 그러나 몇몇 구현에 있어서는 로직의 간결함을 위해 쿠키를 설정하면서 동시에 이를 다름 루틴에 적용 할 필요가 있다. 이때에는 qValueAdd()를 사용하여 링크드 리스트에 값을 강제 추가함으로써 로직을 간결화시킬 수 있다. 단 qCookieSet()은 모든 경우에 쿠키 설정이 성공하는 것이 아니므로, qValueAdd()의 사용은 조심스러워야 한다.

반드시 qContentType()이 호출되기 전에 사용하여야 한다.
Example:char *name = "NAME", *value = "Kim"; // Apply the NAME=Kim information in the current domain and directory for 30 days. qCookieSet(name, value, 30, NULL, NULL, NULL); // Apply the NAME=Kim information to the "/" directory of "ANYTHING.qdecoder.org" // until the browser is shut down. qCookieSet(name, value, 0, "/", ".qdecoder.org", NULL); // As for the followings, cookies will be set up only when security // requirements are satisfied. qCookieSet(name, value, 0, NULL, NULL, "SECURE"); // As for the followings, you can remove cookies. qCookieSet(name, "", -1, NULL, NULL, NULL);

qCookieRemove()

Syntax:void qCookieRemove(char *name, char *path, char *domain, char *secure);
Function:클라이언트(브라우저)의 쿠키를 삭제한다.
Note:인자 path, domain, seure는 qCookieSet()을 통해 쿠키를 설정할 당시의 인자와 같아야 한다.

qCookieRemove()을 통해 쿠키를 삭제했을 경우 링크드 리스트에서 값이 제거되는 시점은 다음번 프로그램 호출시가 된다. 그러나 몇몇 구현에 있어서는 로직의 간결함을 위해 쿠키를 삭제하면서 동시에 이를 다름 루틴에 적용 할 필요가 있다. 이때에는 qValueRemove()를 사용하여 링크드 리스트에 값을 강제 삭제함으로써 로직을 간결화시킬 수 있다. 단 qCookieRemove()는 모든 경우에 쿠키 삭제가 성공하는 것이 아니므로, qValueRemove()의 사용은 조심스러워야 한다.
Example:qCookieSet("NAME", "VALUE", 0, NULL, NULL, NULL); qCookieRemove("NAME", NULL, NULL, NULL); qCookieSet("NAME", "VALUE", 0, "/", NULL, NULL); qCookieRemove("NAME", "/", NULL, NULL); qCookieSet("NAME", "VALUE", 0, "/", "www.qdecoder.org", NULL); qCookieRemove("NAME", "/", "www.qdecoder.org", NULL);

qCookieValue()

Syntax:char *qCookieValue(char *format, ...);
Function:쿠키값을 복귀한다.
Return:쿠키가 존재하면 쿠키값의 포인터, 쿠키가 없으면 NULL
Example:char *cookie; cookie = qCookieValue("NAME"); if(cookie == NULL) qError("Cookies are not set.");

qPrint()

Syntax:int qPrint(void);
Function:프로그램의 디버깅용으로 전달된 인자를 모두 출력한다.
Return:인자의 갯수.
Example:qPrint();

qFree()

Syntax:void qValueAdd(char *name, char *value);
Function:qDecoder()에 의해 할당된 Memory를 해제한다.
Note:qFreeAll() 참조.
Example:qFree();


Session Functions

qSession()

Syntax:int qSession(char *repository);
Function:세션을 시작한다.
Return:새로운 세션일 경우 1, 기존에 생성된 세션일 경우 0.
Note:세션을 사용하기 위해서는 프로그램의 초기에 qSession()을 호출하여야 한다. qSession()은 클라이언트에 32바이트 세션ID만을 쿠키로 저장을 한후, 해당 세션 ID에 대해 설정된 자료는 서버측에 저장을 한다. 기본적으로 세션은 마지막 호출후 1800초후에 파기되며, 이는 qSessionSetTimeout()을 통해 조정할 수 있다.

쿠키가 지원되지 않는 클라이언트는 세션ID가 설정되지 않아서, 해당 클라이언트가 다음번 접속될 때 기존 세션 데이터를 읽어오지 못한다. 이렇게 쿠키가 지원되지 않는 클라이어트(예: WAP Phone)에 세션을 적용할 경우엔 URL에 세션ID를 다음과 같이 세션ID를 명시함으로써 세션을 유지할 수 있다.

http://domain/application?QSESSIONID=ab77bbb49dd61cd510db121a948ab4d9&other=arguments

qSession()은 기본적으로 다음의 세션 변수를 제공한다.

 _Q_SESSIONID   : 세션 ID (ex: ab77bbb49dd61cd510db121a948ab4d9)
 _Q_CREATED-GMT : 세션 생성 GMT 시간 (ex: Thu, 19-Jul-2001 21:50:19 GMT)
 _Q_CREATED     : 세션 생성 시간 (ex: 995579419)
 _Q_CONNECTIONS : 접속 횟수 카운터 (ex: 15)
 _Q_INTERVAL    : 세션 만료 주기/초 (ex: 1800)

세션 데이터는 파일시스템을 통해 기록되는데 유닉스 시스템의 경우 기본적으로 /tmp, 윈도우의 경우 "C:\Windows\Temp"이며, qSession() 호출시 repository 변수에 경로를 지정함으로써 세션 스토리지 위치를 변경할 수 있다. 세션 스토리지에는 "qsession-"으로 시작하는 파일이 생성되며, 자동으로 관리된다. (WIN32 환경에서는 자동 관리되지 않으므로, 정기적으로 repository의 qsession-* 파일을 삭제하여야 한다)

세션 자료는 qSessionFree()나 qSessionSave(), qFreeAll()중 하나가 수행될 때 저장된다.
Example:qSession(NULL); // use default storage qSession("/tmp"); // use /tmp for session storage

qSessionAdd()

Syntax:char *qSessionAdd(char *name, char *format, ...);
Function:세션 변수를 설정한다.
Return:설정된 세션값.
Example:qSessionAdd("name", "qDecoder"); qSessionAdd("cginame", "%s", qCGIname());

qSessionAddInteger()

Syntax:int qSessionAddInteger(char *name, int valueint);
Function:정수형 세션 변수를 설정한다.
Return:설정된 세션값.
Example:qSessionAddInteger("count", 32);

qSessionUpdateInteger()

Syntax:int qSessionUpdateInteger(char *name, int plusint);
Function:정수형 세션 변수를 갱신한다.
Return:갱신된 정수값

qSessionValue()

Syntax:char *qSessionValue(char *format, ...);
Function:변수명에대한 세션값을 복귀한다.
Return:성공시 세션값에 대한 문자열 포인터, 해당 변수가 없을시엔 NULL.
Example:char *value; value = qSessionValue("name"); value = qSessionValue("%d.name", i);

qSessionValueInteger()

Syntax:int qSessionValueInteger(char *format, ...);
Function:정수형 세션변수의 값을 복귀한다.
Return:성공시 정수형 세션값, 실패시 0.
Example:int value; value = qSessionValueInteger("count");

qSessionRemove()

Syntax:void qSessionRemove(char *format, ...);
Function:세션 변수를 삭제한다.
Example:qSessionRemove("name"); qSessionRemove("%d.name", i);

qSessionGetID()

Syntax:char *qSessionGetID(void);
Function:세션 ID를 복귀한다.
Return:32바이트 세션 ID의 문자열 포인터.
Example:char *sessionid; char *sessionidstr[32+1]; sessionid = qSessionGetID(); strcpy(sessionidstr, sessionid);

qSessionGetCreated()

Syntax:time_t qSessionGetCreated(void);
Function:세션이 생성된 시각을 복귀한다.
Return:1970년 1월 1일 0시 0분 0초이후부터 경과한 세션 생성시각에 대한 초.
Example:time_t created; struct tm *gmtime; created = qSessionGetCreated(); gmtime = gmtime(&created);

qSessionSetTimeout()

Syntax:void qSessionSetTimeout(time_t seconds);
Function:세션의 만료기간을 설정한다.
Return:설정된 세션 만료기간.
Note:세션의 기본 만료기간은 1800초이다..
Example:qSessionSetTimeout((time_t)3600);

qSessionPrint()

Syntax:int qSessionPrint(void);
Function:프로그램의 디버깅용으로 세션 변수를 모두 출력한다.
Return:세션 변수의 갯수.
Example:qSessionPrint();

qSessionSave()

Syntax:void qSessionSave(void);
Function:세션 정보를 즉시 저장한다.
Note:qSessionSave()는 qSessionFree()시 자동으로 수행된다. 프로그램의 흐름상
qSessionFree()를 만나기 전에 프로그램이 종료될 가능성이 있을 경우에,
변경된 세션 정보를 확실히 저장하기 위해 명시적으로 사용될 수 있다.
Example:qSessionSave();

qSessionFree()

Syntax:void qSessionFree(void);
Function:세션을 저장하고 할당된 메모리를 해제한다.
Example:qSessionFree();

qSessionDestroy()

Syntax:void qSessionDestroy(void);
Function:세션을 파기한다.
Example:qSessionDestroy();


Configuration File Parsing Functions

qfDecoder()

Syntax:Q_Entry *qfDecoder(char *filename);
Function:파일을 읽어 linked-list에 저장한다. (파일의 행길이 제약없음)
Return:Linked-list의 첫번째 레코드 포인터, 에러시 NULL.
Note:다음과 같은 형식의 파일을 읽어 linked-list에 저장한다.

---- test.conf ----
# this is comment.
name  = Kim
phone = 123-4567
addr  = 한국
-------------------

샵(#)으로 시작되는 행은 주석으로 처리해 해석하지 않는다.
Example:Q_Entry *first; first = qfDecoder("test.conf"); if(first == NULL) qError("File not found.");

qfValue()

Syntax:char *qfValue(Q_Entry *first, char *format, ...);
Function:변수명의 변수값을 얻는다.
Return:성공시 변수값의 포인터, 실패시 NULL.
Example:char *value; value = qfValue(first, "name");

qfiValue()

Syntax:int qfiValue(Q_Entry *first, char *format, ...);
Function:변수값을 정수로 변환후 넘겨준다.
Return:설공시 변수값(숫자 문자열)에 대한 정수값. 변수명이 존재하지 않거나, 해당 값이 정수로 변환 불가능 하면 0 .
Example:int count; count = qfiValue(first, "count");

qfValueFirst()

Syntax:char *qfValueFirst(Q_Entry *first, char *format, ...);
Function:동일한 변수명을 갖는 인자들을 순차적으로 패치할 때 사용.
Return:성공시 동일한 변수명을 갖는 인자들에 대한 첫번째 변수값 포인터를 복귀, 변수명이 없을시 NULL.
Example:char *list; for(list = qfValueFirst("checklist"); list; list = qfValueNext()) { printf("checklist = %s<br>\n", list); }

qfValueNext()

Syntax:char *qfValueNext(void);
Function:qfValueFirst()로 찾는 것을 계속한다.
Return:성공시 변수값의 포인터, 더이상의 동일 변수명이 없을때 NULL.
Example:char *list; for(list = qfValueFirst("checklist"); list; list = qfValueNext()) { printf("checklist = %s<br>\n", list); }

qfPrint()

Syntax:int qfPrint(Q_Entry *first);
Function:프로그램의 디버깅용으로 해석한 인자를 모두 출력한다.
Return:인자의 갯수.
Example:qfPrint(first);

qfFree

Syntax:void qfFree(Q_Entry *first);
Function:할당된 Memory를 반환한다.
Example:qfFree(first);


Configuration String Parsing Functions

qsDecoder()

Syntax:Q_Entry *qsDecoder(char *str);
Function:문자열을 읽어 linked-list에 저장한다. (파일의 행길이 제약없음)
Return:Linked-list의 첫번째 레코드 포인터, 에러시 NULL.
Note:다음과 같은 형식의 문자열을 읽어 linked-list에 저장한다.

---- test.conf ----
# this is comment.
name  = Kim
phone = 123-4567
addr  = 한국
-------------------

샵(#)으로 시작되는 행은 주석으로 처리해 해석하지 않는다.
Example:Q_Entry *FirstRecord; char *str="name=Seung-young Kim\nage=26\naddr=Korea"; FirstRecord = qsDecoder(str);

qsValue()

Syntax:char *qsValue(Q_Entry *first, char *format, ...);
Function:변수명의 변수값을 얻는다.
Return:성공시 변수값의 포인터, 실패시 NULL.
Example:char *value; value = qsValue(first, "name");

qsiValue()

Syntax:int qsiValue(Q_Entry *first, char *format, ...);
Function:변수값을 정수로 변환후 넘겨준다.
Return:설공시 변수값(숫자 문자열)에 대한 정수값. 변수명이 존재하지 않거나, 해당 값이 정수로 변환 불가능 하면 0 .
Example:int count; count = qsiValue(first, "count");

qsValueFirst()

Syntax:char *qsValueFirst(Q_Entry *first, char *format, ...);
Function:동일한 변수명을 갖는 인자들을 순차적으로 패치할 때 사용.
Return:성공시 동일한 변수명을 갖는 인자들에 대한 첫번째 변수값 포인터를 복귀, 변수명이 없을시 NULL.
Example:char *list; for(list = qsValueFirst("checklist"); list; list = qsValueNext()) { printf("checklist = %s<br>\n", list); }

qsValueNext()

Syntax:char *qsValueNext(void);
Function:qsValueFirst()로 찾는 것을 계속한다.
Return:성공시 변수값의 포인터, 더이상의 동일 변수명이 없을때 NULL.
Example:char *list; for(list = qsValueFirst("checklist"); list; list = qsValueNext()) { printf("checklist = %s<br>\n", list); }

qsPrint()

Syntax:int qsPrint(Q_Entry *first);
Function:프로그램의 디버깅용으로 해석한 인자를 모두 출력한다.
Return:인자의 갯수.
Example:qsPrint(first);

qsFree

Syntax:void qsFree(Q_Entry *first);
Function:할당된 Memory를 반환한다.
Example:qsFree(first);


SED: Context Generation Functions

qSedArgAdd()

Syntax:Q_Entry *qSedArgAdd(Q_Entry *first, char *name, char *format, ...);
Function:qSedFile()과 qSedStr()에서 사용할 name, value 쌍 인자를 인자 목록에 추가한다.
Return:인자 목록의 첫번째 포인터.
Example:Q_Entry *args; args = NULL; args = qSedArgAdd(args, "${NAME}", "%s", "Seung-young Kim"); /* recommanded */ args = qSedArgAdd(args, "${HOBBY}", Playing Guitar"); /* not recommanded, but it works */

qSedArgAddDirect()

Syntax:Q_Entry *qSedArgAddDirect(Q_Entry *first, char *name, char *value);
Function:qSedFile()과 qSedStr()에서 사용할 name, value 쌍 인자를 인자 목록에 추가한다.
Return:인자 목록의 첫번째 포인터.
Note:기존의 qSedArgAdd() 함수는 value 값으로 format에 의한 가변인자를 사용하기 때문에 크기가 1024-1 바이트로 제한된다. 따라서 본 함수는 qSedArgAdd()의 확장 함수로써, 보다 큰 크기의 value 값을 삽입하기 위해 사용한다.
Example:Q_Entry *args; char *hugevalue = "...huge...string..."; args = NULL; args = qSedArgAddDirect(args, "${NAME}", hugevalue);

qSedArgPrint()

Syntax:int qSedArgPrint(Q_Entry *first);
Function:프로그램의 디버깅용으로 변수를 모두 출력한다.
Return:인자의 갯수.
Example:qSedArgPrint(first);

qSedArgFree()

Syntax:void qSedArgFree(Q_Entry *first);
Function:qSedArgAdd()에 의해 할당된 Memory를 해제한다.
Example:qSedArgFree(first);

qSedFile()

Syntax:int qSedFile(Q_Entry *first, char *filename, FILE *fpout);
Function:파일에서 지정된 기호를 정의된 문자열로 교체하여 출력하며, 일부 SSI 문법을 지원한다.
Return:성공시 1, 파일을 열 수 없을경우 0.
Note:UNIX 시스템의 SED 명령과 흡사한 기능을 한다.

---- ex) streamedit.html.in ----
<!--#include file="streamedit-header.html.in"-->
<p>Hi <b>${NAME}</b>.
<p>You got a really cool hobby.
<br>I'm sure that your hobby, <b>${HOBBY}</b>, can make your life more compatible.
<p>Bye :)
<!--#include file="streamedit-tailer.html.in"-->
---------------------

qSedFile를 활용하면, 프로그램내에 HTML 코드를 전혀 포함하지 않고도 CGI 프로그래밍을 할 수 있다. UI와 관련된 디버깅 시간을 대폭 줄일 수 있고, 디자인과 개발의 분리작업이 가능하며, 패키지 제품의 경우 사용자 측면에서 손쉽게 커스터 마이징이 가능할 수 있는등의 효용성을 동반할 수 있다.
filename은 입력(대상)파일이고, fpout은 출력 스트림을 의미한다. 결과를 파일로 출력을 하고 자 할경우엔 파일을 "w"로 열어, 해당 파일 포인터를 건네어 주면 되고, 화면 출력하고자 한다면, 그냥 stdout 을 지정하면 된다.

또한, SSI 문법을 해석한다. (현재는 <!--#include file="FILEPATH"--> 만이 지원됨) 문서내 다음과 같은 라인이 있을 경우, 해당 문서를 포함하여 출력되며, 포함되는 문서에 대해서도 교체및 SSI 기능은 그대로 유효하다. (Cascading)

<!--#include file="streamedit-header.html.in"-->

주의) include 되는 파일은 CGI가 실행되는 위치를 기준으로 상대경로 표기 하거나, 시스템 절대경로 표기한다.

문자열 교체를 하지않고, SSI 기능만을 사용코자 할 경우엔 다음과 같이 arg 인자로 NULL 값을 전달한다.

ex) qSedFile(NULL, "streamedit.html.in", stdout);
Example:Q_Entry *args; char *name, *hobby; qContentType("text/html"); name = qValueDefault("Not Found", "name"); hobby = qValueDefault("Not Found", "hobby"); args = NULL; args = qSedArgAdd(args, "${NAME}", name); args = qSedArgAdd(args, "${HOBBY}", hobby); if(qSedFile(args, "streamedit.html.in", stdout) == 0) qError("File not found."); qSedArgFree(args);

qSedStr()

Syntax:int qSedStr(Q_Entry *first, char *srcstr, FILE *fpout);
Function:qSedFile()과 동일한 기능을 하나, 입력을 문자열로 받는다.
Return:qSedFile()과 동일.
Example:Q_Entry *args; char *sp; sp = "My name is ${NAME}."; args = NULL; args = qSedArgAdd(args, "${NAME}", "Seung-young Kim"); qSedStr(args, sp, stdout); qSedArgFree(args);


AWK: Pattern Scanning Functions

qAwkOpen()

Syntax:int qAwkOpen(char *filename, char separator);
Function:파일을 열고, 구분자를 설정한다.
Return:성공시 1, 파일을 열 수 없을경우 0.
Note:UNIX 시스템의 AWK 명령과 흡사한 기능을 한다.

---- ex) /etc/passwd ----
shpark:x:1008:1000:Sang-hyun Park:/home/shpark:/bin/csh
teamwork:x:1011:1000:Seung-young Kim:/home/teamwork:/bin/csh
kikuchi:x:1015:2000:KIKUCHI:/home/kikuchi:/bin/csh
-------------------------
Example:qAwkOpen("/etc/passwd", ':');

qAwkNext()

Syntax:int qAwkNext(char array[][1024]);
Function:한행을 읽어 들여, 인자로 주어진 배열에 저장한다.
Return:성공시 필드 수, 파일의 끝 -1.
Note:한 라인의 총길이는 제한이 없으나, 구분자로 구분되는 각 필드는 1024-1 바이트를 넘어선 안된다.
Example:char array[7][1024]; qAwkOpen("/etc/passwd", ':'); for( ; qAwkNext(array) > 0; ) printf("ID=%s, Name=%s", array[0], array[5]); qAwkClose();

qAwkClose()

Syntax:Q_BOOL qAwkClose(FILE *fp);
Function:오픈된 파일을 닫는다.
Return:성공시 Q_TRUE, 오류시 Q_FALSE
Example:qAwkClose();

qAwkStr()

Syntax:int qAwkStr(char array[][1024], char *str, char delim);
Function:문자열을 구분자로 나눠 인자로 주어진 배열에 저장한다.
Return:분리자로 분리된 필드의 갯수.
Note:문자열의 길이는 제한이 없으나, 구분자로 구분되는 각 필드는 1024-1 바이트를 넘지 않아야 한다.
Example:char *string = "root:*:0:0:Charlie &:/root:/bin/csh"; char array[7][1024]; qAwkStr(array, string, ':');


Search Key Words & Pattern Matching Functions

qArgMake()

Syntax:int qArgMake(char *str, char **qlist);
Function:쿼리를 토큰으로 분리한다. 구분자는 기본적으로 스페이스 문자 이며 쿼리의 앞뒤 공백과 토큰 사이의 중복된 스페이스는 무시된다.
Return:구분된 토큰 수.
Note:검색어 관련 함수군은 질의 문자열을 스페이스와 큰따옴표(") 기준으로 나누어 리스트에 담아주며, 대상 문자열과의 매칭 테스트와 출력에 관련된 함수군을 제공한다.


---- Example ----
Query Input: I am a "pretty girl"
-----------------
     |  |
     V  V
---- qArgMake() ----
qlist[0] = I
qlist[1] = am
qlist[2] = a
qlist[3] = pretty girl
qlist[4] = NULL
Return: 4 (4 Tokens)
--------------------
     |  |
     V  V
---- qArgPrint() ----
'I' (1 bytes)
'am' (2 bytes)
'a' (1 bytes)
'pretty girl' (11 bytes)
---------------------
     |  |
     V  V
---- qArgMatch() ----
Target String: Hi, I'm a pretty boy. Are you pretty girl?
               =  =   =             =       ===========
               0  0   2             2             3
Return: 3 (3 matches: qlist[0], qlist[2], qlist[3])
---------------------
     |  |
     V  V
---- qArgEmprint() ----
Target String..: Hi, I'm a pretty boy. Are you pretty girl?
Result.........: Hi, I'm a pretty boy. Are you pretty girl?
                 =  =   =             =       ===========
                 1  2   3             4             5
Return: 5 (5 matches)
-----------------------
Example:char *query="I am a \"pretty girl\".", *qlist[MAX_TOKENS]; int queries; queries = qArgMake(query, qlist);

qArgMatch()

Syntax:int qArgMatch(char *str, char **qlist);
Function:대소문자를 구분하지 않고 토큰 매칭 테스트를 한다.
Return:특정 문자열에서 발견되는 토큰의 개수를 복귀.
Note:같은 토큰에 대해서는 중복되어 매칭되어도 1회로 계산한다. 중복 매칭을 포함하여 문자열내 총 매칭 카운트를 위해서는 qArgEmprint()의 복귀값을 참고하라. 이 값들은 qArgMake()에서 얻은 토큰의 총 개수로 백분율하여 검색 정확도를 계산하는데 쓰일 수 있다.
Example:int matches; matches = qArgMatch("Hi, I'm a pretty boy. Are you pretty girl?", qlist);

qArgEmprint()

Syntax:int qArgEmprint(int mode, char *str, char **qlist);
Function:문자열에서 토큰과 매칭되는 부분을 볼드(bold)처리하여 출력한다. 대소문자를 구분하지 않는다.
Return:문자열에서 발견된 토큰의 개수를 복귀하며, qArgMatch()와는 다르게 중복 매칭을 포함하여 총 매칭 카운트를 복귀한다.
Note:mode값은 qPrintf()와 동일하며, 일반적인 목적엔 1이 주로 사용될 수 있겠다.
Example:qArgEmprint(1, "Hi, I'm a pretty boy. Are you pretty girl?", qlist);

qArgPrint()

Syntax:int qArgPrint(char **qlist);
Function:프로그램의 디버깅용으로 해석된 토큰을 모두 출력한다.
Example:qArgPrint(qlist);

qArgFree()

Syntax:void qArgFree(char **qlist);
Function:메모리 할당된 qlist를 해제한다.
Example:qArgFree(qlist);


HTTP Response Functions

qContentType()

Syntax:void qContentType(char *mimetype);
Function:MimeType을 출력한다.
Note:여러번 호출되어도 단 한번만 수행된다.
Example:qContentType("text/html"); // when displaying HTML qContentType("/image/gif.jpg"); // when displaying the GIF image

qGetContentFlag()

Syntax:int qGetContentFlag(void);
Function:qContextType()이 호출되었는지를 체크한다.
Return:qContentType()이 이미 호출되었으면 1, 호출되지 않았으면 0.
Example:if(qGetContentFlag() == 0) qCookieRemove("NAME", NULL, NULL, NULL);

qResetContentFlag()

Syntax:void qResetContentFlag(void);
Function:qContentType()의 내부 플래그를 초기 상태로 셋팅한다.
Note:qContentType()은 여러번 호출되어도 한번만 수행이 되는데, 이를 강제적으로 다시 출력하고자 할 경우에 qResetContentFlag()를 수행한 후 qContentType()을 호출하면 중복 출력이 가능하다.
Example:qContentType("text/html"); ...some business logic here... qResetContentFlag(); qContentType("text/html"); ...some business logic here... qResetContentFlag(); qContentType("text/html"); ...some business logic here...

qRedirect()

Syntax:void qRedirect(char *url);
Function:HTTP의 Location: 헤더를 사용해 특정 페이지로 점프한다.
Note:qRedirect는 HTTP 헤더를 사용하므로 해당 프로세스에서 스트림 아웃하는 유일한 출력이어야 한다.
Example:qRedirect("/");

qJavaScript()

Syntax:void qJavaScript(char *format, ...);
Function:자바스크립트 코드를 출력한다.
Note:이 함수는 다음의 내용을 stdout 으로 출력한다.

<script language="JavaScript">
YOUR CODES HERE
</script>
Example:qContentType("text/html"); qJavaScript("alert(\"hello\");");


Encoding/decoding Functions

qURLencode()

Syntax:char *qURLencode(char *str);
Function:문자열을 URL Encoding 한다.
Return:URL Encoding된 문자열이 메모리 할당되어 복귀된다. 해제(free)는 사용자가 하여야 한다.
Note:'@', '.', '/', '\', '-', '_', ':' 문자는 인코딩 하지 않는다.
Example:char *encstr; encstr = qURLencode("Hello!");

qURLdecode

Syntax:char *qURLdecode(char *str);
Function:%xx로 URL Encoding된 문자열을 해독한다.
Return:해독된 문자열 포인터
Note:인자(str)를 직접 수정한다.
Example:char *encstr; qURLdecode(encstr);

qMD5Str()

Syntax:char *qMD5Str(char *string);
Function:문자열에 대한 MD5 핑거프린트(체크섬)을 계산한다.
Return:32 바이트 핑거프린트 문자열 포인터.
Note:복귀 스트링 포인터는 사용자가 매번 free()하는 번거로움을 없애기 위해 메모리를 할당하여 반환치 않고 함수 내부에 static 선언되어 있다. 따라서 함수가 수행될 때 마다 이전 값이 지워짐에 유의하여야 한다. 또한 반환되는 문자열 포인터를 사용하여 직접적으로 수정하거나 free()하여서는 안된다.
Example:printf("Hash Result = %s", MD5Str("Hello")); [Result] Hash Result = 8b1a9953c4611296a827abf8c47804d7

qMD5File()

Syntax:char *qMD5File(char *string);
Function:파일에 대한 MD5 핑거프린트(체크섬)을 계산한다.
Return:32 바이트 핑거프린트 문자열 포인터.
Note:복귀 스트링 포인터는 사용자가 매번 free()하는 번거로움을 없애기 위해 메모리를 할당하여 반환치 않고 함수 내부에 static 선언되어 있다. 따라서 함수가 수행될 때 마다 이전 값이 지워짐에 유의하여야 한다. 또한 반환되는 문자열 포인터를 사용하여 직접적으로 수정하거나 free()하여서는 안된다.
Example:printf("Hash Result = %s", MD5File("qDecoder.tar.Z")); [Result] Hash Result = 499589b930e48996a64317c79e6cc36b

qFnv32Hash()

Syntax:unsigned int qFnv32Hash(char *str, unsigned int max);
Function:This function will be released at 8.1R


String Handling Functions

qPrintf()

Syntax:int qPrintf(int mode, char *format, ...);
Function:printf()와 동일한 사용방법으로 HTML TAG의 적용 유뮤와 자동 Link를 행한다.
Return:성공시 출력한 bytes 갯수, 에러시 EOF.
Note:조합된 스트링의 최대 크기가 10K(1024 * 10 - 1)을 넘으면 안된다.

Mode 00 : Same as printf()
Mode 10  :Mode 0 + Convert

Mode 01 : Print HTML TAG
Mode 11 : Print HTML TAG + Convert

Mode 02 : Print HTML TAG + Auto Link
Mode 12 : Print HTML TAG + Auto Link + Convert

Mode 03 : Print HTML TAG + Auto Link(_top)
Mode 13 : Print HTML TAG + Auto Link(_top) + Convert
Mode 23 : Print HTML TAG + Auto Link(new window)
Mode 33 : Print HTML TAG + Auto Link(new window) + Convert

Mode 04 : Waste HTML TAG
Mode 14 : Waste HTML TAG + Convert

Mode 05 : Waste HTML TAG + Auto Link
Mode 15 : Waste HTML TAG + Auto Link + Convert

Mode 06 : Waste HTML TAG + Auto Link(_top)
Mode 16 : Waste HTML TAG + Auto Link(_top) + Convert
Mode 26 : Waste HTML TAG + Auto Link(new window)
Mode 36 : Waste HTML TAG + Auto Link(new window) + Convert

Convert : " "   -> " "
         "  "  -> "  "
         "   " -> "   "
         "\n"   -> "<br>\n"
         "\r\n" -> "<br>\n"

10 이상의 Mode 값은 <pre> 태그를 사용치 않고서도, 연속된 공백을 화면에 보여주고자 할 때 사용하면 효과적이다. 또한 이 경우엔 화면폭의 변화에 따라 자동으로 줄바꿈이 수행된다.
Example:qPrintf(i, "Mode %d: <font>\"\"</font>\n", i); Mode 0: <font>""</font> Mode 1: <font>""</font> Mode 2: <font>"<a href="/" target=""></a>"</font> Mode 3: <font>"<a href="/" target="_top"></a>"</font> Mode 4: "" Mode 5: "<a href="/" target=""></a>" Mode 6: "<a href="/" target="_top"></a>" Mode 10: <font>""</font><br> Mode 11: <font>""</font><br> Mode 12: <font>"<a href="/" target=""></a>"</font><br> Mode 13: <font>"<a href="/" target="_top"></a>"</font><br> Mode 14: ""<br> Mode 15: "<a href="/" target=""></a>"<br> Mode 16: "<a href="/" target="_top"></a>"<br> qPrintf(i, "Mode %d: ' ', ' ', ' ', ' '\n", i); Mode 0: ' ', ' ', ' ', ' ' Mode 1: ' ', ' ', ' ', ' ' Mode 2: ' ', ' ', ' ', ' ' Mode 3: ' ', ' ', ' ', ' ' Mode 4: ' ', ' ', ' ', ' ' Mode 5: ' ', ' ', ' ', ' ' Mode 6: ' ', ' ', ' ', ' ' Mode 10: ' ', ' &nbsp;', ' &nbsp;&nbsp;', ' &nbsp;&nbsp;&nbsp;'<br> Mode 11: ' ', ' &nbsp;', ' &nbsp;&nbsp;', ' &nbsp;&nbsp;&nbsp;'<br> Mode 12: ' ', ' &nbsp;', ' &nbsp;&nbsp;', ' &nbsp;&nbsp;&nbsp;'<br> Mode 13: ' ', ' &nbsp;', ' &nbsp;&nbsp;', ' &nbsp;&nbsp;&nbsp;'<br> Mode 14: ' ', ' &nbsp;', ' &nbsp;&nbsp;', ' &nbsp;&nbsp;&nbsp;'<br> Mode 15: ' ', ' &nbsp;', ' &nbsp;&nbsp;', ' &nbsp;&nbsp;&nbsp;'<br> Mode 16: ' ', ' &nbsp;', ' &nbsp;&nbsp;', ' &nbsp;&nbsp;&nbsp;'<br>

qPuts()

Syntax:void qPuts(int mode, char *buf);
Function:포맷에 의한 인자 전달이 안된다는 점을 제외하면 qPrintf()와 동일하다.
Note:주어진 인자 buf 자체를 수정하기 때문에, 상수 문자열(ex: str = "문자열")이나 다시 사용되어야 하는 변수를 qPuts()로 출력하진 말아햐 한다. qPuts()가 존재하는 이유는 qPrintf()에서와 같은 인자 스트링의 길이 제한이 없으며 strdup() 함수가 사용되지 않기에 조금 더 빠르기 때문이다.

인자로 전해준 문자열이 변형된다. 따라서 qPuts(mode, "문자열"); 이런식의 상수 문자열 사용은 오류를 잃으킨다. 이때에는 예제에서와 같이 인자를 복사한후 사용한다.
Example:char buf[100]; strcpy(buf, " mailto:nobreak@hongik.com"); qPuts(2, buf); char *buf; buf = strdup(" mailto:nobreak@hongik.com"); qPuts(2, buf); free(buf);

qRemoveSpace()

Syntax:char *qRemoveSpace(char *str);
Function:문자열의 앞뒤 공백과 CR, LF를 제거한다.
Return:성공시 문자열의 포인터, 실패시 NULL.
Note:qRemoveSpace("문자열"); 이런식의 사용은 오류를 잃으킬수 있다. 이때에는 예제에서와 같이 인자를 복사한후 사용한다.
Example:char teststr[100]; strcpy(teststr, " Hello, world \r\n "); qRemoveSpace(teststr); // After deletion, "Hello, world" is inserted in teststr. char *teststr; teststr = strdup(" Hello, world \r\n "); qRemoveSpace(teststr); // After deletion, "Hello, world" is inserted in teststr.

qRemoveTailSpace

Syntax:char *qRemoveTailSpace(char *str);
Function:This function will be released at 8.1R

qStrReplace()

Syntax:char *qStrReplace(char *mode, char *srcstr, char *tokstr, char *word);
Function:문자열에 대한 문자열 및 토큰 치환을 한다.
Return:치환된 스트링 포인터.
Note:'mode' 인자는 "sr"와 같이 두개의 분리된 문자로 구성된 문자열이다.
첫번째 문자는 치환방법을 정의하며 't'나 's'가 위치할 수 있다. 't'는 [t]oken을 의미하며 tokstr 문자열의 각 문자를 토큰으로 소스 문자열 srcstr을 비교하여, 매칭이 되는 문자를 word 문자열로 치환한다. 's'는 [s]tring을 의미하여 tokstr 스트링 자체를 하나의 토큰으로 하여 소스 스트링내에 나타나는 tokstr 매칭 문자열을 word 문자열로 치환한다.

두번째 문자는 치환된 문자열에 대한 기록 형태를 나타내며 'n'과 'r'이 사용될 수 있다. 'n'은 [n]ew를 나타내며 치환된 결과 문자열을 새로운 메모리 공간에 저장하여 해당 포인터를 리턴하게 한다. 따라서 소스 스트링 자체는 원상태가 유지되고 해당 메모리는 사용자 측면에서 free() 되어야 한다. 'r'은 [r]eplace를 의미하며 치환 결과를 srcstr에 덮어 씀을 의미한다. 이때 srcstr이 충분히 여유있다고 가정하므로(편리성의 이유로 메모리 재할당을 하지 않음) [r]eplace 모드를 사용하고자 할 때에는 이 점에 유의하여야 한다.

결과적으로 'mode' 인자는 다음과 같이 4개의 조합 가능한 경우를 갖는다.

 Mode "tn" : [t]oken 치환 & 새로운 공간에 결과를 담아 복귀
 Mode "tr" : [t]oken 치환 & 인자 자체를 수정
 Mode "sn" : [s]tring 치환 & 새로운 공간에 결과를 담아 복귀
 Mode "sr" : [s]tring 치환 & 인자 자체를 수정
Example:Example) int i; char srcstr[256], *retstr; char mode[4][2+1] = {"tn", "tr", "sn", "sr"}; for(i = 0; i < 4; i++) { strcpy(srcstr, "Welcome to the qDecoder project."); printf("before %s : srcstr = %s\n", mode[i], srcstr); retstr = qStrReplace(mode[i], srcstr, "the", "_"); printf("after %s : srcstr = %s\n", mode[i], srcstr); printf(" retstr = %s\n\n", retstr); if(mode[i][1] == 'n') free(retstr); } Result) before tn : srcstr = Welcome to the qDecoder project. after tn : srcstr = Welcome to the qDecoder project. retstr = W_lcom_ _o ___ qD_cod_r proj_c_. before tr : srcstr = Welcome to the qDecoder project. after tr : srcstr = W_lcom_ _o ___ qD_cod_r proj_c_. retstr = W_lcom_ _o ___ qD_cod_r proj_c_. before sn : srcstr = Welcome to the qDecoder project. after sn : srcstr = Welcome to the qDecoder project. retstr = Welcome to _ qDecoder project. before sr : srcstr = Welcome to the qDecoder project. after sr : srcstr = Welcome to _ qDecoder project. retstr = Welcome to _ qDecoder project. Example 2) Convert to SQL String qStrReplace("sr", sqlvalue, "\\", "\\\\"); qStrReplace("sr", sqlvalue, "'", "\\'");

qStr09AZaz()

Syntax:int qStr09AZaz(char *str);
Function:문자열이 0-9, A-Z, a-z로 이루어졌는지 판별한다.
Return:조건에 부합하면 1, 오류시 0.
Example:if(qStr09AZaz("abc1234") == 1) printf("True");

qStrupr()

Syntax:char *qStrupr(char *str);
Function:인자로 주어진 문자열을 모두 대문자로 변환한다.
Return:해당 문자열의 포인터.
Example:char *str; str = strdup("Hello World"); qStrupr(str);

qStrlwr()

Syntax:char *qStrlwr(char *str);
Function:인자로 주어진 소자열을 모두 대문자로 변환한다.
Return:해당 문자열의 포인터.
Example:char *str; str = strdup("Hello World"); qStrlwr(str);

qStristr()

Syntax:char *qStristr(char *big, char *small);
Function:strstr() 함수와 같으나, 대소문자를 구분하지 않고 비교한다.
Return:strstr()과 같음.
Example:printf("%s", qStristr("Hello World", "WORLD"));

qStricmp()

Syntax:int qStricmp(char *s1, char *s2);
Function:strcmp() 함수와 같으나, 대소문자를 구분하지 않는다.
Return:strcmp()와 같음.
Example:if(!qStricmp("Hello", "HELLO")) printf("Equal"); else printf("Differ");

qStrincmp()

Syntax:int qStrincmp(char *s1, char *s2, size_t len);
Function:strncmp() 함수와 같으나, 대소문자를 구분하지 않는다.
Return:strncmp()와 같음.
Example:if(!qStrincmp("Hello World", "HELLO", 5)) printf("Equal"); else printf("Differ");

qitocomma()

Syntax:char *qitocomma(int value);
Function:숫자를 콤마 문자열로 변환한다.
Return:문자로 변환된 스트링 포인터.
Note:복귀 스트링 포인터는 사용자가 매번 free()하는 번거로움을 없애기 위해 메모리를 할당하여 반환치 않고 함수 내부에 static 선언되어 있다. 따라서 qitocomma()는 매번 동일한 스트링 포인터를 반환하게 되며 함수가 수행될 때 마다 이전 값이 지워짐에 유의하여야 한다.
Example:1) (O) example of right usage, when single arguments are used printf("Price = %s", qitocomma(1234567)); Price = 1,234,567 2) (O) example of right usage, when plural arguments are used char a[14+1], b[14+1]; strcpy(a, qitocomma(1234)); strcpy(b, qitocomma(5678)); printf("Price = %s + %s\n", a, b); Price = 1,234 + 5,678 3) (X) example of wrong usage printf("%s %s\n", qitocomma(1234), qitocomma(5678)); Price = 1,234 + 1,234

qStrcat()

Syntax:char *qStrcat(char str, char *format, ...);
Function:This function will be released at 8.1R

qStrdupBetween()

Syntax:char *qStrdupBetween(char *str, char *start, char *end);
Function:This function will be released at 8.1R


File Handling Functions

qfopen()

Syntax:FILE *qfopen(char *path, char *mode);
Function:락(lock)에 의한 파일 오픈 함수
Return:fopen()과 동일
Note:반드시 qfclose() 함수로 파일을 닫아야 한다.
Example:FILE *fp; fp = qfopen("/tmp/report.txt", "w"); ... qfclose(fp);

qfclose()

Syntax:int qfclose(FILE *stream);
Function:qfopen()의 의해 열린 파일 스트림을 닫는다.
Return:fclose()과 동일

qCheckFile()

Syntax:int qCheckFile(char *format, ...);
Function:파일의 존재여부를 파악한다.
Return:파일이 존재 하면 1, 파일이 없으면 0.
Note:Permission에 의해 접근 불가능한 파일도 파일이 없다고 판단한다.
Example:if(qCheckFile("test.dat") == 0) qError("File not found");

qCatFile()

Syntax:int qCatFile(char *format, ...);
Function:파일의 내용을 출력한다.
Return:정상시 출력된 문자수, 에러시 -1.
Example:qContentType("/image/gif.jpg"); qCatFile("/mypic.gif"); qContentType("text/html"); qCatFile("myhtml.html");

qReadFile()

Syntax:char *qReadFile(char *filename, int *size);
Function:파일을 읽어 메모리에 저장후 포인터를 반환한다.
Return:정상시 스트링 포인터, 오류시 NULL.
Note:qReadFile은 실제 파일의 크기보다 1바이트 크게 메모리 할당 하여 스트링 종료문자 '\0'를 삽입한다. 이는 텍스트 파일을 읽어 다루기 편리하도록 함이다. spsize에는 파일에서 읽어들인 캐릭터 개수가 저장된다. 캐릭터 개수가 필요치 않다면 spsize 항목에 NULL 인자를 전달한다.
Example:char *sp, *sp2; int spsize; sp = qReadFile("filename", &spsize); sp2 = qReadFile("filename2", NULL); ... free(sp), free(sp2);

qSaveStr()

Syntax:int qSaveStr(char *sp, int spsize, char *filename, char *mode);
Function:스트링의 내용을 파일에 저장한다.
Return:정상시 저장한 캐릭터 갯수(파일 크기), 오류시 -1.
Note:mode 인자는 fopen 시에 사용되는 mode 값과 같다. qSaveStr은 해당 mode로 파일을 오픈할 것이다. 파일 퍼미션은 호출전의 umask() 설정값에 의존선을 갖는다.
Example:char *sp = "To subscribe qDecoder mailing list\nSend mail to majordomo@qdecoder.org"; int len; umask(022); len = qSaveStr(sp, strlen(sp), "howto-mailing.txt", "w");

qFileSize()

Syntax:long qFileSize(char *filename);
Function:파일의 용량을 byte 단위로 돌려줌.
Return:성공시 파일의 용량, 파일 없음 -1
Example:long size; size = qFileSize("/home/nobreak/sample.pdf");

qfGetLine()

Syntax:char *qfGetLine(FILE *fp);
Function:파일에서 행길이 제약없이 라인을 읽는다.
Return:할당된 메모리 포인터, 파일 끝 NULL.
Note:복귀된 스트링 포인터의 메모리 해제는 사용자가 하여야 한다.
Example:line = qfGetLine(fp);

qfGets()

Syntax:char *qfGets(FILE *fp);
Function:This function will be released at 8.1R

qCmd()

Syntax:char *qCmd(char *cmd);
Function:This function will be released at 8.1R


Validation Functions

qCheckEmail()

Syntax:int qCheckEmail(char *email);
Function:E-mail 주소의 적합성 여부를 판별한다.
Return:적합한 email 주소 1, 부적합 email 주소 0.
Example:qCheckEmail("nobreak@openbird.com");

qCheckURL()

Syntax:int qCheckURL(char *url);
Function:URL 주소의 적합성 여부를 판별한다.
Return:오류가 없으면 1, 규칙에 준하지 않으면 0
Example:qCheckURL("/");


Download Handling Functions

qDownload()

Syntax:int qDownload(char *filename);
Function:클라이언트로 파일을 전송하는데, 파일의 종류에 상관없이 브라우저에 다운로딩 상자가 나타나도록 한다.
Return:성공 전송한 바이트수, 파일 없음 -1.
Note:본 함수는 편의를 위한 qDownloadMime()의 껍대기 함수이다.
Example:qDownload("/home/nobreak/myprg.exe");

qDownloadMime()

Syntax:int qDownloadMime(char *filename, char *mime);
Function:클라이언트로 마임에 준하여 파일을 전송한다.
Return:성공 전송한 바이트수, 파일 없음 -1.
Note:본 함수는 해당 파일을 웹상에 직접 링크하였을 때와 동일한 결과를 갖지만, 사용자 인증이 되어야만 다운로드 할 수 있도록 전처리를 하거나, 웹상에 공개될 수 없는 파일을 특정 프로그램을 통해서만 다운받을 수 있게 하는데 유용하다. mime이 'application/octet-stream'일 경우에는 qDownload()와 동일하다. 또한 스트림이 종료될때 까지 프로세스가 실행되게 되므로, 웹상에도 링크가 걸릴 수 있는 파일인데 다운로딩 카운트등을 위한 전처리로 사용할 경우라면 qRedirect()를 활용하는 것이 좋다.
Example:qDownloadMime("/home/nobreak/myprg.gif", "/image/gif.jpg");


Counter Handling Functions

qCountRead()

Syntax:int qCountRead(char *filename);
Function:카운터 파일을 읽는다.
Return:성공시 카운터값, 에러시 0.
Note:다음과 같은 형식의 카운터 파일을 다룬다.

---- number.dat ----
74
--------------------
Example:int count; count = qCountRead("number.dat");

qCountSave()

Syntax:Q_BOOL qCountSave(char *filename, int number);
Function:지정된 파일명에 카운터 값을 저장(갱신)한다.
Return:성공시 Q_TRUE. 오류시 Q_FALSE.
Example:qCountSave("number.dat", 75);

qCountUpdate()

Syntax:int qCountUpdate(char *filename, int number);
Function:지정된 파일명의 카운터 값을 number만큼 증가시킨다.
Return:성공시 갱신된 카운터값, 에러시 0
Example:int count; count = qCountUpdate("number.dat", -3);


Environment Related Functions

qCGIenv()

Syntax:void qCGIenv(Q_CGIenv *env);
Function:CGI의 환경변수와 시간을 구조체에 저장한다.
Example:Q_CGIenv myenv; qCGIenv(&myenv); /* Q_CGIenv Data Structure */ typedef struct Q_CGIenv Q_CGIenv; struct Q_CGIenv{ char *auth_type; char *content_length; char *content_type; char *document_root; char *gateway_interface; char *http_accept; char *http_accept_encoding; char *http_accept_language; char *http_connection; char *http_cookie; char *http_host; char *http_referer; char *http_user_agent; char *query_string; char *remote_addr; char *remote_host; char *remote_port; char *remote_user; char *request_method; char *request_uri; char *script_filename; char *script_name; char *server_admin; char *server_name; char *server_port; char *server_protocol; char *server_software; char *server_signature; char *unique_id; /* Miscellaneous Informations Supported by qDecoder */ int year, mon, day, hour, min, sec; };

qCGIname()

Syntax:char *qCGIname(void);
Function:환경변수 SCRIPT_NAME에서 프로그램명만을 해석하여 복귀한다.
Return:CGI명을 담고 있는 문자열 포인터를 복귀한다.
Example:char *cginame; cginame = qCGIname();

qGetenvDefault()

Syntax:qGetenvDefault(char *nullstr, char *envname);
Function:getenv()함수와 동일하게 동작하나, NULL 대신 디폴드 스트링을 복귀한다.
Example:char *name; name = qGetenvDefault("/cgi-bin/CrazyWWWBoard.cgi", "SCRIPT_NAME"); name = qGetenvDefault(NULL, "SCRIPT_NAME");


Time Functions

qGetTime()

Syntax:struct tm *qGetTime(void);
Function:시간을 구조체 tm에 저장한다.
Return:구조체 tm의 포인터.
Example:struct tm *mytime; mytime = qGetTime();

qGetGMTime()

Syntax:time_t qGetGMTime(char *gmt, time_t plus_sec);
Function:현재시간+plus_sec을 쿠키에서 사용하는 GMT 문자열 시간으로 변환한다.
Return:1970/1/1(00:00:00)부터 현제까지의 초 + plus_sec.
Example:time_t plus_sec; char gmt[32]; plus_sec = (time_t)300; /* 5min */ qGetGMTime(gmt, plus_sec); printf("%s", gmt); // "Fri, 22-Aug-1997 15:11:30 GMT"

qGetTimeStr()

Syntax:char *qGetTimeStr(void);
Function:시간을 YYYYMMDDhhmmss 형태의 문자열로 저장한다.
Return:내부 static 문자열에 대한 문자열 포인터.
Example:char *timestr; timestr = qGetTimeStr();


Socket Handling Functions

qSocketOpen()

Syntax:int qSocketOpen(char *hostname, int port);
Function:TCP 소켓을 생성한다.
Return:성공시 소켓 디스크립터, 호스트를 찾지 못할경우 -1, 소켓생성 오류시 -2
Example:int sockfd; sockfd = qSocketOpen("www.qdecoder.org", 80);

qSocketClose()

Syntax:int qSocketClose(int sockfd);
Function:소켓을 닫는다.
Return:성공시 0, 실패시 -1.
Example:qSocketClose(sockfd)

qSocketWaitReadable()

Syntax:int qSocketWaitReadable(int sockfd, int timeoutsec);
Function:타임아웃 시간동안 소켓에 데이터가 들어오기를 기다린다.
Note:일반적으로 소켓에 타임아웃을 걸고 데이터를 기다리기 위해서는
소켓을 non-blocking 모드로 설정하여야 하는데, 본 함수는 소켓을
생성시에 non-blocking 모드로 설정하지 않아도, 지정된 시간동안
데이터가 소켓에 도달하지 않을시에 non-blocking 모드에서 처럼
즉각적인 복귀를 지원한다.
Example:int sockstatus; sockstatus = qSocketWaitReadable(sockfd, 10); if(sockstatus != 1) qError("Timeout!");

qSocketRead()

Syntax:int qSocketRead(char *binary, int size, int sockfd, int timeoutsec);
Function:소켓에서 데이터를 읽는다.
Return:성공시 읽은 데이터의 길이, 실패(타임아웃)시 -1.

qSocketGets()

Syntax:int qSocketGets(char *str, int size, int sockfd, int timeoutsec);
Function:스트림에서 읽은 바이트수를 리턴한다. 타임아웃시엔 0, 기타 오류(연결종료)시에는 -1이 복귀된다.
Return:성공시 문자열 포인터, 타임아웃시 NULL.
Note:리턴된 바이트수는 str에 저장된 문자의 수는 아니다. 리턴된 바이트수는 스트림에서 실제 읽은 바이트 수이기 때문에 tailing CR, LF를 카운트 하지만, 실제 str에는 tailing CR, LF를 저장하지 않기 때문이다.

qSocketWrite()

Syntax:int qSocketWrite(char *binary, int size, int sockfd);
Function:소켓에 데이터를 쓴다.
Return:성공시 보낸 데이터 길이, 실패시 -1.

qSocketPuts()

Syntax:int qSocketPuts(char *str, int sockfd);
Function:개행문자를 붙여서 소켓에 데이터를 보낸다.
Return:성공시 1, 실패시 0.

qSocketPrintf()

Syntax:int qSocketPrintf(int sockfd, char *format, ...);
Function:양식에 맞춘 포맷된 문자열을 소켓에 보낸다.
Return:성공시 1, 실패시(호스트 연결이 닫힌 경우 등) 0.
Note:포맷된 형식의 최종 문자열 결과물은 1024-1 바이트를 넘지 않아야 한다.
길이에 제한없이 문자열을 보내기 위해서는 qSocketPuts() 함수를 사용하기 바란다.

qSocketSendFile()

Syntax:int qSocketSendFile(char *filepath, int offset, int sockfd);
Function:파일 데이터를 소켓으로 보낸다.
Return:성공시 전송한 바이트수, 실패시(파일 열기 실패 등) -1.

qSocketSaveIntoFile()

Syntax:int qSocketSaveIntoFile(int sockfd, int size, int timeoutsec, char *filepath, char *mode);
Function:스트림의 데이터를 파일로 바로 저장한다.
Return:성공시 저장한 바이트, 실패시 -1.
Example:qSocketSaveIntoFile(sockfd, reading_length, 10, "/home/savedata/pic.jpg", "w");

qSocketSetNonblock()

Syntax:int qSocketSetNonblock(int sockfd);
Function:소켓을 non-blocking 모드로 설정한다.
Return:성공시 1, 실패시 0.
Note:이 함수는 호환성을 이유로 제공이 되나, 실제 qDecoder에서 non-blocking 모드가
필요한 경우에 대해 모든 함수를 제공하기 때문에, 이 함수를 사용하여 소켓의
모드를 전환할 필요는 없다.

또한 이 함수를 사용한 이후에는, qDecoder에서 제공하는 소켓관련 함수가 정상적으로 동작하지 않으며, 모드 변환 이후의 소켓 핸들링은 사용자 스스로 하여야 한다.

qSocketConv2file()

Syntax:FILE *qSocketConv2file(int sockfd);
Function:소켓을 FILE 디스크립터 형식으로 변환한다.
Return:변환된 FILE 디스크립터.
Note:표준 C에서 제공하는 fprintf(), fscanf() 등의 함수를 이용하여 소켓을 사용할 수 있도록 int 타입의 소켓 디스크립터를 FILE 타입으로 변환한다.

이렇게 FILE 디스크립터로 변환을 한 경우엔, 소켓이 완전 block 모드로 동작되어
타임아웃 등을 설정하기 어려우므로, 특별한 이유가 아니라면 qDecoder의 소켓 관련 함수를 사용하여 구현하길 권장한다.
Example:FILE *sockfp; sockfp = qSocketConv2file(sockfd); fprintf(sockfp, "Hello");


Database Independent Wrapper Functions

qDbInit()

Syntax:Q_DB *qDbInit(char *dbtype, char *addr, int port, char *username, char *password, char *database, Q_BOOL autocommit);
Function:This function will be released at 8.1R

qDbFree()

Syntax:int qDbFree(Q_DB *db);
Function:This function will be released at 8.1R

qDbOpen()

Syntax:Q_BOOL qDbOpen(Q_DB *db);
Function:This function will be released at 8.1R

qDbClose()

Syntax:Q_BOOL qDbClose(Q_DB *db);
Function:This function will be released at 8.1R

qDbGetErrMsg()

Syntax:char *qDbGetErrMsg(Q_DB *db);
Function:This function will be released at 8.1R

qDbPing()

Syntax:Q_BOOL qDbPing(Q_DB *db)
Function:This function will be released at 8.1R

qDbGetLastConnStatus()

Syntax:Q_BOOL qDbGetLastConnStatus(Q_DB *db);
Function:This function will be released at 8.1R

qDbExecuteUpdate()

Syntax:int qDbExecuteUpdate(Q_DB *db, char *pszQuery);
Function:This function will be released at 8.1R

qDbExecuteQuery()

Syntax:Q_DBRESULT *qDbExecuteQuery(Q_DB *db, char *pszQuery);
Function:This function will be released at 8.1R

qDbGetRows()

Syntax:int qDbGetRows(Q_DBRESULT *result);
Function:This function will be released at 8.1R

qDbGetCols()

Syntax:int qDbGetCols(Q_DBRESULT *result);
Function:This function will be released at 8.1R

qDbResultNext()

Syntax:int qDbResultNext(Q_DBRESULT *result);
Function:This function will be released at 8.1R

qDbResultFree()

Syntax:Q_BOOL qDbResultFree(Q_DBRESULT *result);
Function:This function will be released at 8.1R

qDbGetValue()

Syntax:char *qDbGetValue(Q_DBRESULT *result, char *field);
Function:This function will be released at 8.1R

qDbGetInt()

Syntax:int qDbGetInt(Q_DBRESULT *result, char *field);
Function:This function will be released at 8.1R

qDbGetValueAt()

Syntax:char *qDbGetValueAt(Q_DBRESULT *result, int idx);
Function:This function will be released at 8.1R

qDbGetIntAt()

Syntax:int qDbGetIntAt(Q_DBRESULT *result, int idx);
Function:This function will be released at 8.1R

qDbBeginTran()

Syntax:Q_BOOL qDbBeginTran(Q_DB *db);
Function:This function will be released at 8.1R

qDbEndTran()

Syntax:Q_BOOL qDbEndTran(Q_DB *db, Q_BOOL commit);
Function:This function will be released at 8.1R

qDbCommit()

Syntax:Q_BOOL qDbCommit(Q_DB *db);
Function:This function will be released at 8.1R

qDbRollback()

Syntax:Q_BOOL qDbRollback(Q_DB *db);
Function:This function will be released at 8.1R


Log Handling Functions

qLogOpen()

Syntax:Q_LOG *qLogOpen(char *pszLogBase, char *pszFilenameFormat, int nRotateInterval, int nFlushFlag);
Function:This function will be released at 8.1R

qLogClose()

Syntax:int qLogClose(Q_LOG *log);
Function:This function will be released at 8.1R

qLogSetConsole()

Syntax:int qLogSetConsole(Q_LOG *log, int nFlag);
Function:This function will be released at 8.1R

qLogFlush()

Syntax:int qLogFlush(Q_LOG *log);
Function:This function will be released at 8.1R

qLog()

Syntax:int qLog(Q_LOG *log, char *pszFormat, ...);
Function:This function will be released at 8.1R


Error Handling Functions

qError()

Syntax:void qError(char *format, ...);
Function:오류에대한 Message를 출력한다. printf() 함수와 사용법 동일.
Note:조합된 오류 메시지의 최대 크기는 1024-1 byte를 넘지 않아야 한다.
Example:qError("error message"); qError("errors at %s", buf);

qErrorContact()

Syntax:void qErrorContact(char *msg);
Function:오류 메시지의 꼬리말로 qError() 호출시 항상 붙어 출력된다. 일반적으로 제작처등의 고정 정보를 제공하기 위해 사용한다.
Example:qErrorContact("- qDecoder Project."); qErrorContact(NULL); // disable (default)

qErrorLog()

Syntax:void qErrorLog(char *file);
Function:qError() 함수를 부를때 전달되는 오류 메시지들이 기록되는 로그파일을 설정한다.
Note:로그를 기록할때 본파일을 직접 호출하는것이 아니라, qErrorLog("logs/error.log") 와같이 프로그램 초기에 호출하면 그 후 qError()가 호출될때마다, 'logs/error.log' 파일에 로그가 자동 기록 된다.
Example:qErrorLog("/tmp/error.log"); // enable log qErrorLog(NULL); // disable log (default)


Miscellaneous Functions

qFreeAll()

Syntax:void qFreeAll(void);
Function:qDecoder에 의해 할당된 모든 메모리를 반환한다.
Note:qFreeAll()은 내부적으로 qFree(), qSessionFree()를 호출한다. 프로그램이 종료하는 시점에 qFree(), qSessionFree()등을 별도로 호출할 필요없이 qFreeAll()을 사용하면 관계된 모든 메모리를 한번에 반환할 수 있다.
Example:qDecoder(); qSession(NULL); ... ... ... qFreeAll();

qReset()

Syntax:void qReset(void);
Function:qDecoder에 의해 할당된 모든 메모리를 반환하고 qDecoder를 초기화 한다.
Note:Daemon 형태의 반복적 프로그램을 작성하거나 qDecoder를 새롭게 초기화 하고자 할 때 본 함수가 사용될 수 있다. qReset()은 linked-list를 포함하여 자체적으로 할당한 메모리를 모두 반환하고 내부 정적 변수들을 초기 상태로 환원시키는 작업을 한다. qReset()을 사용할때 qFreeAll()등을 별도로 사용할 필요는 없다.
Example:while(1) { qDecoder(); qSession(NULL); ... ... ... qReset(); }

qUniqueID()

Syntax:char *qUniqueID(void);
Function:호출될 때 마다 유일한 32바이트 문자열을 반환한다.
Return:32 바이트 문자열에대한 문자열 포인터.
Note:복귀 스트링 포인터는 사용자가 매번 free()하는 번거로움을 없애기 위해 메모리를 할당하여 반환치 않고 함수 내부에 static 선언되어 있다. 따라서 함수가 수행될 때 마다 이전 값이 지워짐에 유의하여야 한다. 또한 반환되는 문자열 포인터를 사용하여 직접적으로 수정하거나 free()하여서는 안된다.
Example:char *uniqueid; uniqueid = qUniqueID();


[Home] [About] [Examples] [Changes] [Download] [SVN Repository] [Install] [Reference]