==========
MFile
==========

MFile Framework 에 대한 필수 API 를 정의

---------
File API
---------

File IO 기능에 대한 API 를 제공




파일 생성
--------------


.. js:function:: M.file.create( options )

    .. versionchanged:: 2.2.0

    :param Object options: 설정 값
    :param String options.path: 파일 및 폴더 경로
    :param String options.type: 파일 및 폴더 여부 (FILE:파일 타입,DIR:폴더 타입)

    * File 및 directory를 생성한다.


    Surrogate Keys: 위 옵션키들과 같은 하위 버전 호환을 위한 대체 옵션 값들
        * name = path
        * alias = path
        * source = path
        * option = type


Example:

	* 폴더 생성
	
	.. code-block:: javascript

		var result = M.file.create({
			'type': 'DIR',
			'path': 'doc://temp'
		});

		console.log(result);
		
	* 파일 생성
	
	.. code-block:: javascript

		var result = M.file.create({
			type: 'FILE',
			path: 'doc://temp/hello.txt'
		});


파일 읽기
--------------

.. js:function:: M.file.read( setting )

	.. versionchanged:: 2.2.0
	
	:param Object setting: 설정 값
	:param String setting.path: 파일 및 폴더 경로
	:param String setting.encoding: 파일 인코딩 (UTF-8, EUC-KR, BASE64)
	:param String setting.indicator: 파일 로딩시 표시할 indicator의 message
	:param function setting.callback: 파일 읽기 완료 후 callback 되는 함수

		.. js:function:: callback(result)
	
			:param Object status: status 상태 코드 (SUCCESS:성공 코드, FAIL:실패 코드)
			:param Object result: 파일 정보
			:param String result.message: 메세지
			:param int result.size: 파일 데이터 길이
			:param String result.data: 파일의 text 데이터 (바이너리 파일의 경우 base64 데이터), 값이 [BLOB] 인 경우 읽을 수 없는 바이너리 파일
			:param String result.path: 파일의 Scheme URL 경로
			:param String result.fullpath: 파일의 전체 경로


	Surrogate Keys: 위 옵션키들과 같은 하위 버전 호환을 위한 대체 옵션 값들
		* name = path
		* alias = path
		* source = path
		* encode = encoding
		* load = callback
		* onload = callback


Example:

	* text 파일 읽기

	.. code-block:: javascript
		
		M.file.read({
			path: 'doc://temp/hello.txt',
			encoding: 'UTF-8',
			indicator: true,
			callback: function(status,result){
				console.log(status + JSON.stringify(result));
			}
		});

	* 바이너리 파일 읽기

	.. code-block:: javascript
		
		M.file.read({
			path: '/storage/emulated/0/DCIM/Camera/sample_img.png',
			encoding: 'BASE64',
			indicator: true,
			callback: function(status,result){
				console.log(status + JSON.stringify(result));

				var imgView = document.getElementById('imageView');

				//mime-type은 별도로 스크립트에서 지정 필요
				imgView.src = "data:image/png;base64,"+result.data; 
			}
		});

.. js:function:: M.file.read( setting, callback )

	.. versionchanged:: 2.2.0
	
	:param Object setting: 설정 값
	:param String setting.path: 파일 및 폴더 경로
	:param String setting.encoding: 파일 인코딩 (UTF-8, EUC-KR, BASE64)
	:param String setting.indicator: 파일 로딩시 표시할 indicator의 message
	:param function callback: 파일 읽기 완료 후 callback 되는 함수

	* File 의 Contents를 읽어 반환한다.


Example:

.. code-block:: javascript
	
	M.file.read({
		path: 'doc://temp/hello.txt',
		encoding: 'UTF-8',
		indicator: true,
	}, function(status,result){
			console.log(status + JSON.stringify(result));
		});



파일 삭제
--------------

.. js:function:: M.file.remove( setting )

	.. versionchanged:: 2.2.0
	
	:param Object setting: 설정 정보
	:param String setting.path: 파일 및 폴더 경로

	* File 및 directory 를 삭제한다.


	Surrogate Keys: 위 옵션키들과 같은 하위 버전 호환을 위한 대체 옵션 값들
		* name = path
		* alias = path
		* source = path
		* option = type



Example:
	
	* 폴더 삭제
	
	.. code-block:: javascript
	
		var result = M.file.remove({
			type: 'DIR',
			path: 'doc://temp/'
		});

		M.tool.log(result);
		alert(JSON.stringify(result));
	
	* 파일 삭제

	.. code-block:: javascript

		var result = M.file.remove({
			path: 'doc://temp/hello.txt'
		});

		console.log(result);




파일 정보
--------------

.. js:function:: M.file.info( setting )

	.. versionchanged:: 2.2.0
	
	:param Object setting: 파일 정보
	:param String setting.path: (source) 원본 경로

	* File 및 directory의 정보를 가져온다.


	Surrogate Keys: 위 옵션키들과 같은 하위 버전 호환을 위한 대체 옵션 값들
		* name = path
		* alias = path
		* source = path


Example:

.. code-block:: javascript
	
	var result = M.file.info({
		path: 'doc://temp/'
	});

	console.log(result);




파일 정보 (목록)
--------------

.. js:function:: M.file.list( setting )

	.. versionchanged:: 2.2.0
	
	:param Object setting: 파일 정보
	:param String setting.path: (source) 원본 경로
	:param String setting.filter: 파일 및 폴더 여부 (FILE:파일 타입,DIR:폴더 타입)

	* File 및 directory의 정보를 가져온다.


	Surrogate Keys: 위 옵션키들과 같은 하위 버전 호환을 위한 대체 옵션 값들
		* name = path
		* alias = path
		* source = path
		* type = filter


Example:

.. code-block:: javascript
	
	var result = M.file.list({
		path: 'doc://temp/',
		filter: 'DIR'
	});

	console.log(result);





파일 복사
--------------

.. js:function:: M.file.copy( setting )

	.. versionchanged:: 2.2.0
	
	:param Object setting: 설정 정보
	:param String setting.type: 파일 및 폴더 여부 (FILE:파일 타입,DIR:폴더 타입)
	:param String setting.source: (source) 원본 경로
	:param String setting.destination: (destination) 복사될 경로
	:param boolean setting.overwrite: 덮어쓰기 여부 
	:param String setting.indicator: 파일 복사시 표시할 indicator 여부
	:param function setting.progress: 파일 복사 중 진행 상태를 알려주는 함수
		
		.. js:function:: progress(total, current)
	
			:param String total: 복사할 전체 파일 크기
			:param String current: 복사된 파일 크기
			


	:param function setting.finish: 파일 복사 완료 후 callback 되는 함수

		.. js:function:: finish(status, result)
	
			:param String status: status 상태 코드 (SUCCESS:성공 코드, FAIL:실패 코드}
			:param String result: 복사된 파일 정보
			:param String result.message: 메세지
			:param int result.size: 파일 데이터 길이
			:param String result.data: 파일의 text 데이터, 값이 [BLOB] 인 경우 바이너리 파일 
			:param String result.path: 파일의 Scheme URL 경로
			:param String result.fullpath: 파일의 전체 경로


	Surrogate Keys: 위 옵션키들과 같은 하위 버전 호환을 위한 대체 옵션 값들
		* path = path
		* from = path
		* alias = path
		* source = path
		* to = destination
		* onprogress = progress
		* onfinish = finish
		* callback = finish


Example:

.. code-block:: javascript
	
	M.file.copy({
		type: 'FILE',
		source: 'doc://temp/hello.txt',
		destination: 'doc://temp/hello1.txt',
		indicator: true,
		progress: function(total, current, setting){
			console.log(total, current);
		},
		finish: function(result){
			console.log(result);
		}
	});


.. js:function:: M.file.copy( setting, callback )

	.. versionchanged:: 2.2.0
	
	:param Object setting: 설정 정보
	:param String setting.type: 파일 및 폴더 여부 (FILE:파일 타입,DIR:폴더 타입)
	:param String setting.source: (source) 원본 경로
	:param String setting.destination: (destination) 복사될 경로
	:param boolean setting.overwrite: 덮어쓰기 여부 
	:param String setting.indicator: 파일 복사시 표시할 indicator 여부
	:param function setting.progress: 파일 복사 중 진행 상태를 알려주는 함수
		
		.. js:function:: progress(total, current)
	
			:param String total: 복사할 전체 파일 크기
			:param String current: 복사된 파일 크기
			


	:param function callback: 파일 복사 완료 후 callback 되는 함수

	* File 및 directory 를 복사한다.


Example:

.. code-block:: javascript
	
	M.file.copy({
		type: 'FILE',
		source: 'doc://temp/hello.txt',
		destination: 'doc://temp/hello1.txt',
		indicator: true,
		progress: function(total, current, setting) {
			console.log(total, current);
		}
	}, function(result) {
		console.log(result);
	});






파일 이동
--------------

.. js:function:: M.file.move( setting )

	.. versionchanged:: 2.2.0
	
	:param Object setting: 설정 정보
	:param String setting.type: 파일 및 폴더 여부 (FILE:파일 타입,DIR:폴더 타입)
	:param String setting.source: (source) 원본 경로
	:param String setting.destination: (destination) 복사될 경로
	:param boolean setting.overwrite: 덮어쓰기 여부 
	:param String setting.indicator: 파일 복사시 표시할 indicator 여부
	:param function setting.progress: 파일 복사 중 진행 상태를 알려주는 함수
		
		.. js:function:: progress(total, current)
	
			:param String total: 복사할 전체 파일 크기
			:param String current: 복사된 파일 크기
			


	:param function setting.finish: 파일 복사 완료 후 callback 되는 함수

		.. js:function:: finish(status, result)
	
			:param String status: status 상태 코드 (SUCCESS:성공 코드, FAIL:실패 코드}
			:param String result: 복사된 파일 정보
			:param String result.message: 메세지
			:param int result.size: 파일 데이터 길이
			:param String result.data: 파일의 text 데이터, 값이 [BLOB] 인 경우 바이너리 파일 
			:param String result.path: 파일의 Scheme URL 경로
			:param String result.fullpath: 파일의 전체 경로



	Surrogate Keys: 위 옵션키들과 같은 하위 버전 호환을 위한 대체 옵션 값들
		* path = path
		* from = path
		* alias = path
		* source = path
		* to = destination
		* onprogress = progress
		* onfinish = finish
		* callback = finish


Example:

.. code-block:: javascript
	
	M.file.move({
		type: 'FILE',
		source: 'doc://temp/hello.txt',
		destination: 'doc://temp/hello1.txt',
		indicator: true,
		progress: function(total, current, setting){
			console.log(total, current);
		},
		finish: function(result){
			console.log(result);
		}
	});


.. js:function:: M.file.move( setting, callback )

	.. versionchanged:: 2.2.0
	
	:param Object setting: 설정 정보
	:param String setting.type: 파일 및 폴더 여부 (FILE:파일 타입,DIR:폴더 타입)
	:param String setting.source: (source) 원본 경로
	:param String setting.destination: (destination) 복사될 경로
	:param boolean setting.overwrite: 덮어쓰기 여부 
	:param String setting.indicator: 파일 복사시 표시할 indicator 여부
	:param function setting.progress: 파일 복사 중 진행 상태를 알려주는 함수
		
		.. js:function:: progress(total, current)
	
			:param String total: 복사할 전체 파일 크기
			:param String current: 복사된 파일 크기
			


	:param function callback: 파일 복사 완료 후 callback 되는 함수

	* File 및 directory 를 이동한다.


Example:

.. code-block:: javascript
	
	M.file.move({
		type: 'FILE',
		source: 'doc://temp/hello.txt',
		destination: 'doc://temp/hello1.txt',
		indicator: true,
		progress: function(total, current, setting) {
			console.log(total, current);
		}
	}, function(result) {
		console.log(result);
	});



파일 쓰기
--------------

.. js:function:: M.file.write( setting )

	.. versionchanged:: 2.2.0
	
	:param Object setting: 설정 정보
	:param String setting.path: 파일 및 폴더 경로
	:param String setting.contents: 데이터
	:param String setting.encoding: 파일 인코딩 (UTF-8, EUC-KR)
	:param String setting.indicator: 파일 생성시 표시할 indicator
	:param function setting.callback: 파일 쓰기 완료 후 callback 되는 함수


	Surrogate Keys: 위 옵션키들과 같은 하위 버전 호환을 위한 대체 옵션 값들
		* name = path
		* alias = path
		* source = path
		* data = contents
		* encode = encoding
		* finish = callback
		* onfinish = callback


Example:

.. code-block:: javascript
	
	M.file.write({
		path: 'doc://temp/hello.txt',
		contents: '안녕하세요.',
		encoding: 'UTF-8',
		callback: function(result){
			console.log(result);
		} 
	});


.. js:function:: M.file.write( setting, callback )

	.. versionchanged:: 2.2.0
	
	:param Object setting: 설정 정보
	:param String setting.path: 파일 및 폴더 경로
	:param String setting.contents: 데이터
	:param String setting.encoding: 파일 인코딩 (UTF-8, EUC-KR)
	:param String setting.indicator: 파일 생성시 표시할 indicator
	:param function callback: 파일 쓰기 완료 후 callback 되는 함수

	* File에 Contents를 쓴다.

Example:

.. code-block:: javascript
	
	M.file.write({
		path: 'doc://temp/hello.txt',
		contents: '안녕하세요.',
		encoding: 'UTF-8', 
	}, function(result) {
		console.log(result);
	});