Contacts 디바이스 API 가이드 프로그램

Contacts 디바이스 API 가이드 프로그램은 모바일 스마트 디바이스의 Contacts 관련 기능을 JavaScript 기반으로 제어 및 확인할 수 있도록 지원한다.
또한, 연락처 조회 기능과 연락처 정보를 서버로 백업하기 기능, 백업된 연락처 정보로 복구하기 기능 구현 시 참고 및 활용될 수 있도록 한다.

본 가이드 프로그램 에서는 Contacts 기능을 가이드 할 수 있도록 연락처 조회 기능, 연락처 정보 백업 기능,
백업된 연락처로 복구 기능 를 제공하고 있다.

• 문제 : 폰갭 라이브러리를 사용해서 연락처를 복원할때 복원된 ID는 새로 부여된다.
• 해결 방안 : 새로운 ID를 서버로 동기화 하여 해결.

function fn_egov_contactIdUpdate(param,isComplete) {
    var url = "/ctt/xml/updateContacts.do";
    var acceptType = "xml";
    var params = {contactsList : {contactsList : param}};
    
    window.plugins.EgovInterface.post(url, acceptType, params, function(xmldata) {		
        console.log('DeviceAPIGuide fn_egov_contactBackupCountSuccess request Completed');
        $.mobile.hidePageLoadingMsg('a');
        if($(xmldata).find("resultState").text() == "OK"){
            if(isComplete) {
                jAlert($(xmldata).find("resultMessage").text() +'개의 연락처가 동기화 되었습니다.', '정보', 'c');
            } else {
                jAlert('서버에 저장된 연락처 개수와 복원된 연락처 개수가 다릅니다.\n다시 복원 해주세요.', '정보', 'c');
            }            
        }else{
            jAlert($(xmldata).find("resultMessage").text(), '오류', 'c');
        }
    });    
}

폰갭에서 특정 외부 도메인이나 외부 도메인의 하위 도메인을 사용해야할 경우,
Res/xml/config.xml에서 <access origin=“” />에 외부 도메인 주소를 추가 설정해야 외부 도메인에 접속할 수 있다.

Contacts 디바이스API 가이드 프로그램은 크게 Contacts 연락처 조회, 연락처 정보 백업, 백업된 연락처로 복구 기능으로 구성되어 있다.

• 연락처 객체를 생성한다.

var myContact = navigator.contacts.create({"displayName": "Test User"});

• 연락처를 검색 한다.
  

navigator.contacts.find(contactFields, contactSuccess, contactError, contactFindOptions);

var options = new ContactFindOptions();
options.filter="Bob"; 
var fields = ["displayName", "name"];
navigator.contacts.find(fields, onSuccess, onError, options);

• 연락처를 저장 한다.

// create a new contact object
var contact = navigator.contacts.create();
contact.displayName = "Plumber";
contact.nickname = "Plumber";       //specify both to support all devices

// populate some fields
var name = new ContactName();
name.givenName = "Jane";
name.familyName = "Doe";
contact.name = name;

// save to device
contact.save(onSuccess,onError);

• 연락처를 복사 한다.

var clone = contact.clone();
clone.name.givenName = "John";
console.log("Original contact name = " + contact.name.givenName);
console.log("Cloned contact name = " + clone.name.givenName);

• 연락처를 제거 한다.

function onSuccess() {
    alert("Removal Success");
};

function onError(contactError) {
    alert("Error = " + contactError.code);
};

// remove the contact from the device
contact.remove(onSuccess,onError);

- contactFields

- ContactName

- ContactField

- ContactAddress

- ContactOrganization

- ContactFindOption

- ContactError

• CONTACT

Contacts 디바이스 API 가이드 프로그램에서 제공하는 모바일 디바이스의 Contacts 관련 기능을 활용하기 위하여 필요한 항목 및 그 환경 설정은 다음과 같다.

<plugins>
    <!--전자정부 Interface 디바이스 API를 사용하기 위한 Phonegap Plugin 클래스-->
    <plugin name="EgovInterfacePlugin" value="kr.go.egovframework.hyb.plugin.EgovInterfacePlugin" />
    <!--전자정부 Contacts 디바이스 API를 사용하기 위한 Phonegap Plugin 클래스-->
    <plugin name="Contacts" value="org.apache.cordova.ContactManager"/>
</plugins>

    <!--전자정부 Interface 디바이스 API에서 사용하기 위한 서버경로 설정-->
    <?xml version="1.0" encoding="utf-8"?>
    <resources>
	<string name="SERVER_URL">http://192.168.100.222:8080/DeviceAPIGuideTotal_Web_V1.7.1</string>
    </resources>

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.READ_CONTACTS" />
<uses-permission android:name="android.permission.WRITE_CONTACTS" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

<sqlMap resource="egovframework/sqlmap/hyb/add/dvc/EgovContactsAndroidAPIGuide_SQL_[DB명].xml"/>

Contacts 디바이스API 가이드 프로그램은 크게 Contacts 연락처 조회, 연락처 정보 백업, 백업된 연락처로 복구
기능으로 구성되어 있다.

function fn_egov_move_localContactList(){	
    $.mobile.showPageLoadingMsg('a');
    var fields = ["displayName", "name", "phoneNumbers", "emails"];
    navigator.contacts.find(fields, fn_egov_contactListSuccess, fn_egov_fail);
}

function fn_egov_contactListSuccess(contacts) {
    console.log('DeviceAPIGuide fn_egov_contactListSuccess Success');
    var theList = $('#listView');
    theList.html("");
    contactsList = contacts;	
    nPageCount = 0;
    fn_egov_showList(true);
	
    $.mobile.hidePageLoadingMsg('a');
    $.mobile.changePage("#contactList", "slide", false, false);
	
    theList.listview("refresh");
	
    setTimeout(loadiScrollList, 1000);
}

function fn_egov_move_localContactDetail(index)
{
    var displayName = "";
    var phoneNumber = "";
    var email = "";
    
    displayName = contactsList[index].displayName;
	
    if(contactsList[index].phoneNumbers != null) 
    {
    	for(var j=0; j<contactsList[index].phoneNumbers.length; j++) 
        {
    	    if(contactsList[index].phoneNumbers[j].type == "mobile")
            {
    		phoneNumber = contactsList[index].phoneNumbers[j].value;
    		break;
    	    }
        }
    }
    if(contactsList[index].emails != null)
    {
        for(var j=0; j<contactsList[index].emails.length; j++) 
        {
            email = contactsList[index].emails[j].value;
            break;
        }
    }
    
    document.getElementById('detailIndex').value = index;
    document.getElementById('detailName').value = (displayName==null)?'이름없음':displayName;
    document.getElementById('detailPhone').value = phoneNumber;
    document.getElementById('detailEmail').value = email;

    $.mobile.changePage("#contactDetail", "slide", false, false);
}

function fn_egov_contactLocalDelete()
{
    var index = $("#detailIndex").val();
    contactsList[index].remove(fn_egov_removeSuccess,fn_egov_fail);
}

리스트:연락처의 상세 조회를 호출한다.
+ 10개더보기:연락처 목록 10개를 더 보여준다.
삭제:연락처를 삭제 한다

function fn_egov_contactBackupCountSuccess(contacts) 
{	
    console.log('DeviceAPIGuide fn_egov_contactBackupCountSuccess Success');
    contactsList = contacts;
	
    var url = "/ctt/xml/selectBackupCount.do";
    var acceptType = "xml";

    var params = {uuid :  device.uuid};
	
    // get the data from server
    window.plugins.EgovInterface.post(url, acceptType, params, function(xmldata) {		
        console.log('DeviceAPIGuide fn_egov_contactBackupCountSuccess request Completed');
        $.mobile.hidePageLoadingMsg('a');
        if($(xmldata).find("resultState").text() == "OK"){
			
            var html = '<div class="ui-block-a"><label align="center"><h3>' + String(contactsList.length) + '</h3></label></div>';
            html += '<div class="ui-block-b"><label align="center"><h3>' + $(xmldata).find("totCount").text() +'</h3></label></div>';
			
            var theList = $('#deviceBackupCount');
            theList.html(html);
			
            $.mobile.changePage("#contactBackup", "slide", false, false);
        }else{			
            jAlert($(xmldata).find("resultMessage").text(), '오류', 'c');
        }
    });	
}

function fn_egov_contactBackup() 
{
    //3G 사용시 과금이 발생 할 수 있다는 경고 메시지 표시
    if(!fn_egov_network_check(false)) {
        return;
    }
    
    if(contactsList.length == 0) {
        return;
    }
	
    $.mobile.showPageLoadingMsg('a');
	
    var param = [];	
    for(var index = 0; index < contactsList.length ; index++) {
        var displayName = '';
        var phoneNumber = '';
        var email = '';
		
        if(contactsList[index].displayName != null) {
            displayName = contactsList[index].displayName;
        }
		
        if(contactsList[index].phoneNumbers != null) {
            for(var j=0; j<contactsList[index].phoneNumbers.length; j++) {
                if(contactsList[index].phoneNumbers[j].type == "mobile"){
                    phoneNumber = contactsList[index].phoneNumbers[j].value;
                    break;
                }
            }
        }
        if(contactsList[index].emails != null) {
            for(var j=0; j<contactsList[index].emails.length; j++) {
                email = contactsList[index].emails[j].value;
                break;
            }
        }
        param.push({uuid:device.uuid, contactId:contactsList[index].id, name:displayName, telNo:phoneNumber, emails:email, useYn:'Y'});
    }

	
    var url = "/ctt/xml/addContactsInfo.do";
    var acceptType = "xml";
    var params = {contactsList : {contactsList : param}};
	
    window.plugins.EgovInterface.post(url, acceptType, params, function(xmldata) {		
        console.log('DeviceAPIGuide fn_egov_contactBackupCountSuccess request Completed');
        $.mobile.hidePageLoadingMsg('a');
        if($(xmldata).find("resultState").text() == "OK"){
            jAlert($(xmldata).find("resultMessage").text(), '정보', 'c');
			
            var html = '<div class="ui-block-a"><label align="center"><h3>' + String(contactsList.length) + '</h3></label></div>';
            html += '<div class="ui-block-b"><label align="center"><h3>' + $(xmldata).find("totCount").text() +'</h3></label></div>';
			
            var theList = $('#deviceBackupCount');
            theList.html(html);
        }else{
            jAlert($(xmldata).find("resultMessage").text(), '오류', 'c');
        }
    });	
}

연락처백업:디바이스의 연락처를 서버로 백업한다.

function fn_egov_contactRecoveryCountSuccess(contacts) {	
    console.log('DeviceAPIGuide fn_egov_contactRecoveryCountSuccess Success');
    contactsList = contacts;
	
    var url = "/ctt/xml/selectBackupCount.do";
    var acceptType = "xml";
    var params = {uuid :  device.uuid};	
	
    // get the data from server
    window.plugins.EgovInterface.post(url, acceptType, params, function(xmldata) {		
        console.log('DeviceAPIGuide fn_egov_contactBackupCountSuccess request Completed');
        $.mobile.hidePageLoadingMsg('a');
        if($(xmldata).find("resultState").text() == "OK"){			
            var html = '<div class="ui-block-a"><label align="center"><h3>' + String(contactsList.length) + '</h3></label></div>';
            html += '<div class="ui-block-b"><label align="center"><h3>' + $(xmldata).find("totCount").text() +'</h3></label></div>';
			
            var theList = $('#deviceRecoveryCount');
            theList.html(html);
			
            $.mobile.changePage("#contactRecovery", "slide", false, false);
        } else {
            jAlert($(xmldata).find("resultMessage").text(), '오류', 'c');
        }
    });
}

function contactRecoveryCallBack(ContactData)
{
    var id = ContactData["id"];
    var name = ContactData["name"];
    var telNo = ContactData["telNo"];
    var email = ContactData["emails"];
    
    var options = new ContactFindOptions();
    options.filter=String(id); 
    var fields = ["id"];
    navigator.contacts.find(fields, 
                            function(contacts)
                            {					    						          
                                if(contacts.length != 0) 
                                {
                                    contacts[0].remove(function(contact){},fn_egov_fail);
                                }
                            
                                var contactname = new ContactName();
                                contactname.middleName = name;
                            
                                var myContact = navigator.contacts.create({"name":contactname});
                            
                                var phoneNumbers = [2];
                                phoneNumbers[0] = new ContactField('work', telNo, false);
                                phoneNumbers[1] = new ContactField('mobile', telNo, false); 
                                phoneNumbers[2] = new ContactField('home', telNo, false); 
                                myContact.phoneNumbers = phoneNumbers;
                            
                                var emails = [2];
                                emails[0] = new ContactField('work', email, false);
                                emails[1] = new ContactField('home', email, false);
                                myContact.emails = emails;
                            
                                myContact.save(function(contact)
                                               {					            		
                                                   recoveryParam.push({uuid:device.uuid, contactId:id, newId:contact.id});
                                                   if(listCount === recoveryParam.length)
                                                   {
                                                       $.mobile.hidePageLoadingMsg('a');
                                                       confirm(String(listCount) + '개의 연락처가 복원되었습니다. 저장된 연락처 정보를 서버와 동기화 합니다.');
                                                       $.mobile.showPageLoadingMsg('a');
                                                       fn_egov_contactIdUpdate();	
                                                   }
                                               },fn_egov_fail);					            					            	
                            
			    }, function(contactError){}, options);
}

function fn_egov_contactIdUpdate(param,isComplete) {
    var url = "/ctt/xml/updateContacts.do";
    var acceptType = "xml";
    var params = {contactsList : {contactsList : param}};
    
    window.plugins.EgovInterface.post(url, acceptType, params, function(xmldata) {		
        console.log('DeviceAPIGuide fn_egov_contactBackupCountSuccess request Completed');
        $.mobile.hidePageLoadingMsg('a');
        if($(xmldata).find("resultState").text() == "OK"){
            if(isComplete) {
                jAlert($(xmldata).find("resultMessage").text() +'개의 연락처가 동기화 되었습니다.', '정보', 'c');
            } else {
                jAlert('서버에 저장된 연락처 개수와 복원된 연락처 개수가 다릅니다.\n다시 복원 해주세요.', '정보', 'c');
            }
            
            var fields = ["displayName", "name", "phoneNumbers", "emails"];
            navigator.contacts.find(fields, function(contacts){
                contactsList = contacts;
                var html = '<div class="ui-block-a"><label align="center"><h3>' + String(contactsList.length) + '</h3></label></div>';
                html += '<div class="ui-block-b"><label align="center"><h3>' + $(xmldata).find("totCount").text() +'</h3></label></div>';
                
                var theList = $('#deviceRecoveryCount');
                theList.html(html);
            }, fn_egov_fail);
            
        }else{
            jAlert($(xmldata).find("resultMessage").text(), '오류', 'c');
        }
    });    
}

연락처복원:서버에 백업된 연락처로 복구한다.

• 디바이스 API 가이드(Android) 프로젝트를 마우스 오른쪽 버튼으로 클릭 후 “Run As”탭의 “Android Application”을 클릭하면 가이드 프로그램이 빌드되어 안드로이드 디바이스에 설치 된다.

• “Android Device Chooser” 창이 나타나면 해당 디바이스를 선택 후 “OK” 버튼을 선택한다.

• 에뮬레이터를 이용한 실행 화면

• 디바이스를 이용한 실행 화면

• ContactsAPI 서버사이드 가이드 프로그램의 실행은 프로젝트를 마우스 오른쪽 버튼을 클릭 한후 Run As>Run On Server 버튼을 통해 실행 할 수 있다.

• 빌드가 성공적으로 수행 되면 이클립스의 콘솔 창에서 'Server Startup in xxx ms' 메시지를 확인 할 수 있다.

디바이스 어플리케이션에서 발생한 오류 내용 확인 및 디버깅을 위해서는 폰갭 프레임워크에서 제공하는 console.log를 이용할 수 있다. console.log 함수는 자바스크립트 구문에서 사용할 수 있는 디버그 코드로 이클립스에서 확인 할 수 있다.

console.log의 작성 방법은 다음과 같다.

function fn_egov_contactListSuccess(contacts) {
    console.log('DeviceAPIGuide fn_egov_contactListSuccess Success');
    var theList = $('#listView');
    theList.html("");
    ...
}

디버깅 코드가 실행 되면 아래와 같은 메시지를 개발도구의 콘솔 메시지 창에서 볼 수 있다.

Contacts 디바이스 API 가이드 프로그램 에서는 디버깅을 위하여 다음과 같이 콘솔 정보를 출력한다.

Contacts 디바이스 API 가이드 다운로드 : Click 새 창 열림

• UX/UI 라이브러리 : jQuery MobileClick 새 창 열림
  
• Phonegap 4.3.0 : Click 새 창 열림