====== PPPOE API 명세서 ======
PPPOE API 와 동작 방식에 대해 상세히 서술했다.
====== About This Document ======
===== Revision History =====
| Version | Date | Comment | Author |
| 1.0 | 2013-9-26 | 최초 작성 | 시스템 소프트웨어3팀 김우종 선임연구원 |
| 1.1 | 2013-10-30 | 업데이트 | 시스템 소프트웨어3팀 김우종 선임연구원 |
===== Purpose =====
본 문서는 IP 카메라 상에서 PPPOE 기능을 사용하기 위해서 알아야 할 PPPOE 동작과 이 때 실행되는 API 에 대한 설명을 기술하고 있다. 이 문서를 통해 PPPOE 의 동작을 좀더 쉽게 이해할 수 있고 나아가서는 디버깅 및 기능 개선 하는데 소요되는 시간을 줄일 수 있을 것이라 기대한다.
===== Conventions and Acronyms =====
==== Codes ====
소스코드와 API 함수 표기는 굴림 글꼴로 표시한다.
==== Notes & Cautions ====
내용 중 알아두면 편리한 참고 사항과 반드시 알아야 하는 중요 사항을 다음과 같이 표시한다.

| <Note> | 내용 중 알아두면 편리한 각종 참고 사항 |
| <Caution> | 내용 중 반드시 알아야 하는 중요한 사항 |
==== Acronyms ====
본 문서는 다음과 같은 약어를 사용한다.

| Acronym | Description |
| PPPOE | The Point-to-Point Protocol over Ethernet (PPPoE) is a network protocol for encapsulating PPP frames inside Ethernet frames. It is used mainly either |
| ISP | Internet Service Provider |
====== Overview ======
PPPOE 를 사용하기 위해서는 pppoe 를 지원하는 커널과 rp-pppoe 라는 프로그램이 있어야 한다. 이에 대한 자세한 내용은 [[computer:technology:PPPOE]] 문서를 참고한다.
전체적인 동작 시나리오는 다음과 같다.
  - ISP 에 가입된 ID 와 패스워드를 입력한다.
  - 입력된 데이터는 특정 파일에 저장되고, 이 파일을 참조하여 ppp 를 실행한다. 
  - 접속 시, ppp0 라는 인터페이스가 생성되며 연결이 성공하면 이를 통해 통신하게 된다.
  - 이후 인증이 실패하면, ppp0 인터페이스가 삭제된다.

참고로 PPPOE 의 경우, ISP 마다 설정 및 접속 방법이 상이할 수 있다.
====== PPPOE Operation ======
===== Initialization =====
부팅 시에 pppoe 관련 커널 모듈이 로딩(insmod) 된다.
===== Connection =====
접속 API 가 호출되면, 암호가 입력된 파일을 이용하여 pppd 를 실행한다. 이후 dhcp client 를 실행하여 IP 주소를 받아온다. 접속되었는지 여부는 주기적으로 PPP0 인터페이스의 존재유무로 판단한다.
===== Disconnection =====
접속을 끊는다. 현재 접속된 상태에서 강제로 접속을 끊는다. wpa_supplication 에 접속 끊음 명령을 내린다.
====== API Reference Guide ======
API 와 그에 사용되는 Structure 에 대한 설명을 하고 있다. 
===== Structures =====
==== PPPOE_STATUS_T ====
PPPOE API 를 실행한 후 결과값을 저장하는 구조체. 이 값을 통해 원하는 대로 API 가 실행되었는지 여부를 판단한다.
<code text>
typedef enum
{
    PPPOE_OK = 0,         // 성공
    PPPOE_FAIL = -1      // 실패
}PPPOE_STATUS_T;
</code>
==== PPPOE_STATUS_INFO_T ====
접속 상태 여부를 저장하는 구조체. 현재 접속 상태 정보를 알 수 있다. 
<code text>
typedef struct
{
    int status;                           // 접속 상태 여부 (1 = 접속, 0 = 비접속)
}PPPOE_STATUS_INFO_T;
</code>
===== Common API Functions =====
==== PPPOE_Connection ====
| Description | ID 와 패스워드를 인자로 받아 접속을 시도한다 |
| Syntax | PPPOE_STATUS_T PPPOE_Connection(char* id, char* password) |
| Parameters | id(IN) - ISP 에 등록된 ID |
|  | password(IN) -  ISP 에 등록된 패스워드 |
| Return Value | If the function succeeds, the return value is PPPOE_OK. |
|  | If the function fails, the return is PPPOE_FAIL. |
| Remarks | PPPOE 가 Initialization 된 이후에 호출가능하다. 입력된 인자와 함께 쉘 스크립트가 실행되면, pppd 가 실행된다 |
| See Also | [[pppoe_api|pppoe api 명세서]] |
| Details | 호출되면, /srv/wifi/pppoe.sh 가 실행되며, 이는 pppd 를 실행한다 |

pppoe.sh 파일은 아래와 같다.
<code text>
#!/bin/sh

cp /etc/ppp/pap-secrets /tmp/
cp /etc/ppp/peers/dsl-provider /tmp/
cp /etc/ppp/chap-secrets /tmp

echo \"$1\" \* \"$2\" >> /tmp/chap-secrets
echo \"$1\" \* \"$2\" >> /tmp/pap-secrets
echo user \"$1\" >> /tmp/dsl-provider

/srv/wifi/pppd call dsl-provider
</code>
==== Code ====
<code text>
PPPOE_STATUS_T PPPOE_Connection(char* id, char* password)
{
    char tmp[256] = {0,};

    int ret; 

    sprintf(tmp, "/srv/wifi/pppoe.sh %s %s", id, password);

    ret = proxy_시스템(tmp, PROXY_TYPE_SYSTEM, 10);          // 한글 주의

    if(ret != 0)
    {    
        printf("\nPPPOE_Disconnection error code : %d\n", WEXITSTATUS(ret));
        return PPPOE_FAIL;
    }    

    return PPPOE_OK;
} 
</code>
==== Example ====
<code text>
        sleep(3);

        char* id = "test";
        char* password = "test";

        PPPOE_Connection(id, password);
</code>
==== PPPOE_GetStatus ====
| Description | PPPOE 가 접속되었는지 여부를 확인한다. |
| Syntax | PPPOE_STATUS_T PPPOE_GetStatus(int *status) |
| Parameters | status(IN) - 접속 상태 정보(1 = 접속, 0 = 접속안됨) |
| Return Value | If the function succeeds, the return value is PPPOE_OK. |
|  | If the function fails, the return is PPPOE_FAIL. |
| Remarks | PPPOE 가 Initialization 된 이후에 호출가능하다. /proc/sys/net/ipv4/conf/ppp0 파일 생성 여부로 판단한다 |
| See Also | [[pppoe_api|pppoe api 명세서]] |
| Details | None |

==== Code ====
<code text>
#define PPPOE_STATUS_FILE "/proc/sys/net/ipv4/conf/ppp0"     

PPPOE_STATUS_T PPPOE_GetStatus(int *status)
{
    FILE *file;

    *status = 0; 

    file = fopen(PPPOE_STATUS_FILE, "r");
    
    if(file == NULL)
    {    
        printf("Not connect PPPOE!\n");
        *status = 0; 
    }    
    else 
    {    
        printf("Connect PPPOE!\n");
        fclose(file);
        *status = 1; 
    }    

    return PPPOE_OK;
}
</code>
==== Example ====
<code text>
int status = 0;

PPPOE_GetStatus(&status);

if(status == 1)
 printf("connect");
else
 printf("not connect");
</code>
==== PPPOE_Disconnection ====
| Description | PPPOE 접속을 끊는다 |
| Syntax | PPPOE_STATUS_T PPPOE_Disconnection(void) |
| Parameters | None |
| Return Value | If the function succeeds, the return value is PPPOE_OK. |
|  | If the function fails, the return is PPPOE_FAIL. |
| Remarks | PPPOE 가 Initialization 된 이후에 호출가능하다. killall 로 해당 pppd 프로세스를 종료시킨다 |
| See Also | [[pppoe_api|pppoe api 명세서]] |
| Details | None |

==== Code ====
<code text>
PPPOE_STATUS_T PPPOE_Disconnection(void)
{
    char tmp[256] = {0,};

    int ret;

    sprintf(tmp, "killall pppd");

    ret = proxy_시스템(tmp, PROXY_TYPE_SYSTEM, 10);                   // 한글 주의

    if(ret != 0)
    {
        printf("\nPPPOE_Disconnection error code : %d\n", WEXITSTATUS(ret));
        return PPPOE_FAIL;
    }

    return PPPOE_OK;
}
</code>
==== Example ====
<code text>
PPPOE_Disconnection();
</code>

----
{{indexmenu>:#1|skipns=/^(wiki|etc|diary|playground)$/ skipfile=/^(todays|about|guestbook)$/ nsort rsort}}
----